tuile 0.4.0 → 0.6.0

data/sig/tuile.rbs

@@ -17,9 +17,10 @@ module Tuile
   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).
+  # via {StyledString} / {Color}, which produce **SGR** sequences ("Select
+  # Graphic Rendition", `ESC [ <params> m` — e.g. `\e[31m` red, `\e[1m`
+  # bold, `\e[0m` reset). Host apps may also use Rainbow, which emits the
+  # same form.
   module Ansi
     RESET: String
   end
@@ -188,6 +189,113 @@ module Tuile
     attr_reader height: Integer
   end
 
+  # An immutable terminal color. Accepts the three forms ANSI/SGR understands:
+  # 
+  # - a Symbol from {COLOR_SYMBOLS} — 8 standard + 8 bright named colors
+  #   (SGR 30..37 / 90..97 for fg, 40..47 / 100..107 for bg)
+  # - an Integer 0..255 — the 256-color palette (SGR 38;5;N / 48;5;N)
+  # - an Array of three Integers 0..255 — 24-bit RGB (SGR 38;2;R;G;B / 48;2;R;G;B)
+  # 
+  # A constant per named color is pre-defined (`Color::RED`, `Color::BRIGHT_BLUE`,
+  # …) so callers can reach for `Color::RED` instead of building one each time.
+  # The 256-color palette gets the same treatment via {PALETTE_NAMES}:
+  # `Color::CADET_BLUE`, `Color::DODGER_BLUE1`, `Color::GREY37`, … — the
+  # standard xterm chart names for indices 16..255, each an exact palette cell.
+  # {.coerce} accepts anything {.new} accepts plus `nil` (terminal default) and
+  # an existing {Color} (returned as-is), so APIs that accept colors typically
+  # take `[Color, nil]` and pass through {.coerce}.
+  # 
+  # ```ruby
+  # Color.new(:red)              # named
+  # Color.new(42)                # 256-color palette
+  # Color.new([255, 100, 0])     # RGB
+  # Color::RED                   # constant
+  # Color.palette(42)            # 256-color palette, explicit
+  # Color.rgb(255, 100, 0)       # 24-bit RGB, explicit
+  # Color.hex("#ff6400")         # 24-bit RGB from a CSS-style hex string
+  # Color.coerce(:red)           # accepts raw forms, returns Color
+  # Color.coerce(nil)            # nil → nil
+  # ```
+  # 
+  # Which entry point to use is a deliberate policy split. High-traffic
+  # call sites ({StyledString} and friends) stay lenient and {.coerce} raw
+  # forms — you don't want factory ceremony on every styled span.
+  # Declaration sites ({Theme}, defined once per app) are strict and take
+  # only {Color} instances, where `Color.palette(130)` documents itself in
+  # a way the bare `130` (palette index? RGB channel?) does not.
+  # 
+  # {#to_ansi} renders a full SGR escape (`"\e[31m"`); {#sgr_codes} returns the
+  # raw numeric codes so callers (notably {StyledString}) can combine them with
+  # other SGR attributes in a single sequence.
+  class Color
+    COLOR_SYMBOLS: ::Array[Symbol]
+    PALETTE_NAMES: ::Hash[Symbol, Integer]
+
+    # Coerces the input to a {Color}. `nil` passes through unchanged (callers
+    # use `nil` for the terminal default); an existing {Color} is returned
+    # as-is; otherwise the value is fed to {.new}.
+    # 
+    # _@param_ `value`
+    def self.coerce: ((Color | Symbol | Integer | ::Array[Integer])? value) -> Color?
+
+    # A color from the 256-color palette (SGR 38;5;N / 48;5;N). Same as
+    # `Color.new(index)`, but the name says what the bare integer is.
+    # 
+    # _@param_ `index` — palette index, 0..255.
+    def self.palette: (Integer index) -> Color
+
+    # A 24-bit RGB color (SGR 38;2;R;G;B / 48;2;R;G;B). Same as
+    # `Color.new([r, g, b])`, but with the channels spelled out.
+    # 
+    # _@param_ `red` — 0..255.
+    # 
+    # _@param_ `green` — 0..255.
+    # 
+    # _@param_ `blue` — 0..255.
+    def self.rgb: (Integer red, Integer green, Integer blue) -> Color
+
+    # A 24-bit RGB color from a CSS-style hex string — for when the value
+    # comes from a hex source (a designer's palette, a CSS variable). The
+    # leading `#` is optional, digits are case-insensitive, and the CSS
+    # 3-digit shorthand expands as in CSS (`"#345"` → `"#334455"`).
+    # 4/8-digit alpha forms are rejected: SGR has no alpha channel, and
+    # silently dropping it would lie about the rendered color.
+    # 
+    # _@param_ `string` — e.g. `"#333333"`, `"5F9EA0"`, `"#333"`.
+    # 
+    # _@return_ — same value form as {.rgb} — `Color.hex("#333") ==
+    # Color.rgb(51, 51, 51)`.
+    def self.hex: (String string) -> Color
+
+    # _@param_ `value` — see class-level docs for the three accepted forms.
+    def initialize: ((Symbol | Integer | ::Array[Integer]) value) -> void
+
+    # SGR parameter codes for emitting this color as either a foreground
+    # (`target: :fg`) or background (`target: :bg`). Returned as an array so
+    # callers can splice them into a multi-attribute SGR (e.g. bold + color).
+    # 
+    # _@param_ `target` — `:fg` or `:bg`.
+    def sgr_codes: (?Symbol target) -> ::Array[Integer]
+
+    # Full SGR escape sequence for this color (e.g. `"\e[31m"`). Useful for
+    # `print`-style direct emission; for composing with other attributes use
+    # {#sgr_codes} instead.
+    # 
+    # _@param_ `target` — `:fg` or `:bg`.
+    def to_ansi: (?Symbol target) -> String
+
+    # _@param_ `other`
+    def ==: (Object other) -> bool
+
+    def hash: () -> Integer
+
+    def inspect: () -> String
+
+    # The underlying raw representation — a Symbol, Integer, or frozen
+    # Array<Integer>.
+    attr_reader value: (Symbol | Integer | ::Array[Integer])
+  end
+
   # A point with `x` and `y` integer coordinates, both 0-based.
   # 
   # @!attribute [r] x
@@ -204,6 +312,213 @@ module Tuile
     attr_reader y: Integer
   end
 
+  # A set of semantic colors the built-in components read when painting.
+  # The current theme lives at {Screen#theme}; components must look it up
+  # at paint time (inside `repaint`) rather than caching values, so that
+  # assigning {Screen#theme=} restyles everything via a single
+  # invalidate-everything pass.
+  # 
+  # The primary API is the rendering helpers — {#active_bg},
+  # {#active_border}, {#input_bg}, {#hint} — which wrap a plain string in
+  # the token's SGR color (on the channel appropriate for the token's
+  # role) and reset:
+  # 
+  #   screen.theme.active_bg("[ Ok ]")   # => "\e[48;5;59m[ Ok ]\e[0m"
+  #   screen.theme.hint("quit")          # => "\e[38;5;109mquit\e[0m"
+  # 
+  # The helpers pass content through verbatim, so input may carry other
+  # escape sequences (e.g. {Component::Window} feeds its border string,
+  # cursor moves included). For span-aware styling — applying a token to a
+  # {StyledString} while preserving per-span colors — use the `*_color`
+  # readers instead (e.g. {Component::List} highlights its cursor row via
+  # `with_bg(theme.active_bg_color)`). Rule of thumb: plain chrome text →
+  # helper; structured text → `*_color` reader + {StyledString}.
+  # 
+  # Two built-in themes are provided: {DARK} (the default; the colors Tuile
+  # has always used) and {LIGHT} (counterparts legible on light terminal
+  # backgrounds). A custom theme is one `with` away:
+  # 
+  #   screen.theme = Theme::DARK.with(active_border_color: Color::CYAN)
+  # 
+  # Tokens deliberately cover only the *accents* Tuile paints. Everything
+  # else inherits the terminal's own default foreground/background, which
+  # already matches the user's terminal theme perfectly — that's why there
+  # is no global `bg`/`fg` token.
+  # 
+  # Every token is a {Color} — and must be passed as one. Unlike the
+  # lenient {Color.coerce} call sites elsewhere in the framework, a theme
+  # is declared once per app, so it takes only {Color} instances: at a
+  # declaration site `Color.palette(130)` documents itself in a way the
+  # bare `130` does not (palette index? RGB channel?) — and the named
+  # palette constants (`Color::DARK_ORANGE3` *is* 130; see
+  # {Color::PALETTE_NAMES}) go one step further.
+  # 
+  # ## App-specific tokens
+  # 
+  # Beyond the built-in tokens, an app can carry its own colors in
+  # {#custom} — a frozen `Hash{Symbol => Color}` member. Look them up with
+  # {#[]} (fail-fast: a typo raises `KeyError`) and render with the
+  # generic {#fg} / {#bg} helpers:
+  # 
+  #   theme = Theme::DARK.with(custom: { accent: Color::DARK_ORANGE })
+  #   theme[:accent]              # => Color, e.g. for StyledString#with_fg
+  #   theme.fg(:accent, "NEW")    # => "\e[38;5;208mNEW\e[0m"
+  # 
+  # Apps wanting semantic readers can subclass — `Data#with` preserves the
+  # subclass, so an `AppTheme` stays an `AppTheme` through `with`:
+  # 
+  #   class AppTheme < Tuile::Theme
+  #     def accent(text) = fg(:accent, text)
+  #   end
+  # 
+  # Pair the dark and light variants in a {ThemeDef} and hand it to
+  # {Screen#theme_def=} so OS appearance flips pick the right one.
+  # 
+  # @!attribute [r] active_bg_color
+  #   Background highlight of the component the user is interacting with:
+  #   the {Component::List} cursor row, the focused {Component::TextField} /
+  #   {Component::TextArea} well, the focused {Component::Button}. "Active"
+  #   matches the {Component#active?} focus-chain flag — this is the
+  #   focus/selection highlight in conventional UI terms.
+  #   @return [Color]
+  # @!attribute [r] active_border_color
+  #   Foreground of a {Component::Window} border when the window is on the
+  #   active (focus) chain.
+  #   @return [Color]
+  # @!attribute [r] input_bg_color
+  #   Resting background "well" of {Component::TextField} /
+  #   {Component::TextArea} when *not* active — visibly a field, but
+  #   distinctly subtler than {#active_bg_color}.
+  #   @return [Color]
+  # @!attribute [r] hint_color
+  #   Foreground of keyboard-shortcut captions in status-bar hints (the
+  #   "quit" in "q quit") — see {#hint}.
+  #   @return [Color]
+  # @!attribute [r] custom
+  #   App-specific color tokens; empty in the built-in themes. Frozen —
+  #   build a changed theme via `with(custom: ...)`. Prefer {#[]} for
+  #   lookups (it fail-fasts on typos); read this directly to enumerate
+  #   the tokens.
+  #   @return [Hash{Symbol => Color}]
+  class Theme
+    DARK: Theme
+    LIGHT: Theme
+
+    # _@param_ `active_bg_color`
+    # 
+    # _@param_ `active_border_color`
+    # 
+    # _@param_ `input_bg_color`
+    # 
+    # _@param_ `hint_color`
+    # 
+    # _@param_ `custom` — app-specific tokens, see {#custom}.
+    def initialize: (
+                      active_bg_color: Color,
+                      active_border_color: Color,
+                      input_bg_color: Color,
+                      hint_color: Color,
+                      ?custom: ::Hash[Symbol, Color]
+                    ) -> void
+
+    # Looks up an app-specific token from {#custom}.
+    # 
+    # _@param_ `token`
+    def []: (Symbol token) -> Color
+
+    # Renders `text` in the foreground color of the app-specific `token`
+    # — the generic counterpart of {#hint} for {#custom} tokens.
+    # 
+    # _@param_ `token`
+    # 
+    # _@param_ `text`
+    # 
+    # _@return_ — ANSI-rendered text, ending with an SGR reset.
+    def fg: (Symbol token, String text) -> String
+
+    # Renders `text` on the background color of the app-specific `token`
+    # — the generic counterpart of {#active_bg} for {#custom} tokens.
+    # 
+    # _@param_ `token`
+    # 
+    # _@param_ `text`
+    # 
+    # _@return_ — ANSI-rendered text, ending with an SGR reset.
+    def bg: (Symbol token, String text) -> String
+
+    # Renders `text` on the {#active_bg_color} background.
+    # 
+    # _@param_ `text`
+    # 
+    # _@return_ — ANSI-rendered text, ending with an SGR reset.
+    def active_bg: (String text) -> String
+
+    # Renders `text` in the {#active_border_color} foreground. Content
+    # passes through verbatim, so it may embed non-SGR escapes (cursor
+    # moves in a border string).
+    # 
+    # _@param_ `text`
+    # 
+    # _@return_ — ANSI-rendered text, ending with an SGR reset.
+    def active_border: (String text) -> String
+
+    # Renders `text` on the {#input_bg_color} background.
+    # 
+    # _@param_ `text`
+    # 
+    # _@return_ — ANSI-rendered text, ending with an SGR reset.
+    def input_bg: (String text) -> String
+
+    # Renders `text` in the {#hint_color} foreground, for status-bar hints,
+    # e.g. `"q #{screen.theme.hint("quit")}"`. The color is baked into the
+    # returned String, so strings built this way do *not* restyle when the
+    # theme changes — rebuild them instead (the framework's own call sites
+    # rebuild on every status-bar refresh).
+    # 
+    # _@param_ `text`
+    # 
+    # _@return_ — ANSI-rendered text, ending with an SGR reset.
+    def hint: (String text) -> String
+
+    # The single sanctioned place for verbatim SGR wrapping: `text` is not
+    # parsed or validated, so callers may embed non-SGR escapes. Emits the
+    # same bytes `StyledString.styled(text, ...).to_ansi` would for plain
+    # text.
+    # 
+    # _@param_ `text`
+    # 
+    # _@param_ `color`
+    # 
+    # _@param_ `target` — `:fg` or `:bg`.
+    def wrap: (String text, Color color, Symbol target) -> String
+
+    # Background highlight of the component the user is interacting with:
+    # the {Component::List} cursor row, the focused {Component::TextField} /
+    # {Component::TextArea} well, the focused {Component::Button}. "Active"
+    # matches the {Component#active?} focus-chain flag — this is the
+    # focus/selection highlight in conventional UI terms.
+    attr_reader active_bg_color: Color
+
+    # Foreground of a {Component::Window} border when the window is on the
+    # active (focus) chain.
+    attr_reader active_border_color: Color
+
+    # Resting background "well" of {Component::TextField} /
+    # {Component::TextArea} when *not* active — visibly a field, but
+    # distinctly subtler than {#active_bg_color}.
+    attr_reader input_bg_color: Color
+
+    # Foreground of keyboard-shortcut captions in status-bar hints (the
+    # "quit" in "q quit") — see {#hint}.
+    attr_reader hint_color: Color
+
+    # App-specific color tokens; empty in the built-in themes. Frozen —
+    # build a changed theme via `with(custom: ...)`. Prefer {#[]} for
+    # lookups (it fail-fasts on typos); read this directly to enumerate
+    # the tokens.
+    attr_reader custom: ::Hash[Symbol, Color]
+  end
+
   # The TTY screen. There is exactly one screen per app.
   # 
   # A screen runs the event loop; call {#run_event_loop} to do that.
@@ -322,7 +637,7 @@ module Tuile
     # 
     #   screen.register_global_shortcut(Keys::CTRL_L,
     #                                   over_popups: true,
-    #                                   hint: "^L #{Rainbow("log").cadetblue}") do
+    #                                   hint: "^L #{screen.theme.hint("log")}") do
     #     log_popup.open
     #   end
     # 
@@ -330,7 +645,7 @@ module Tuile
     # 
     # _@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.
+    # _@param_ `hint` — preformatted status-bar hint (e.g. `"^L #{screen.theme.hint("log")}"`). When nil (default) the shortcut is silent in the status bar. The colors are baked into the string, so a later {#theme=} does not restyle it — re-register if needed.
     def register_global_shortcut: (String key, ?over_popups: bool, ?hint: String?) -> void
 
     # Removes a shortcut previously installed by {#register_global_shortcut}.
@@ -398,6 +713,23 @@ module Tuile
     # but only one focused.
     def cursor_position: () -> Point?
 
+    # Startup color scheme: `:light` when {TerminalBackground.detect}
+    # reports a light terminal background, `:dark` otherwise (including
+    # when detection is inconclusive). Runs in the constructor — the
+    # OSC 11 reply arrives on stdin, which is only safe to read before
+    # {EventQueue#start_key_thread} owns it. {FakeScreen} overrides this
+    # to pin `:dark`, keeping specs deterministic and off the test
+    # runner's TTY.
+    # 
+    # _@return_ — `:dark` or `:light`.
+    def detect_scheme: () -> Symbol
+
+    # An OS appearance flip arrived (mode-2031 report): remember the
+    # scheme and apply the matching member of {#theme_def}.
+    # 
+    # _@param_ `scheme` — `:dark` or `:light`.
+    def on_color_scheme: (Symbol scheme) -> void
+
     # 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
@@ -481,6 +813,22 @@ module Tuile
     # _@return_ — current screen size.
     attr_reader size: Size
 
+    # The color {Theme} built-in components read at paint time: the member
+    # of {#theme_def} matching the terminal background detected at
+    # construction (see {TerminalBackground.detect}; inconclusive means
+    # dark). While the event loop runs, terminals supporting mode 2031
+    # push OS appearance changes ({EventQueue::ColorSchemeEvent}) and the
+    # screen re-picks from {#theme_def}.
+    attr_accessor theme: Theme
+
+    # The app's {ThemeDef} — the dark/light {Theme} pair the screen picks
+    # {#theme} from, at startup and on every OS appearance flip. Starts as
+    # {ThemeDef.default} ({ThemeDef::DEFAULT} unless reassigned — tests
+    # do, see {ThemeDef.default=}). Assigning a custom definition is the
+    # durable way to theme an app: unlike a bare {#theme=}, it survives
+    # the user toggling the OS appearance.
+    attr_accessor theme_def: ThemeDef
+
     # _@return_ — the event queue.
     attr_reader event_queue: EventQueue
 
@@ -502,6 +850,52 @@ module Tuile
     end
   end
 
+  # A sizing policy for a slot whose position is managed by a parent
+  # component (e.g. {Component::Window#footer}). Resolves one dimension at a
+  # time via {#resolve}, so the same value works for widths and heights.
+  # 
+  # Three policies exist:
+  # 
+  # - {FILL} — take everything the slot offers;
+  # - {WRAP_CONTENT} — take the component's natural extent (its
+  #   {Component#content_size}), clamped to the slot;
+  # - {.fixed} — take exactly the given number of cells, clamped to the slot.
+  # 
+  # Note that {WRAP_CONTENT} only makes sense for components that report a
+  # natural {Component#content_size} ({Component::Label}, {Component::Button},
+  # {Component::List}, …). Input components ({Component::TextField} et al.)
+  # report {Size::ZERO}, so a wrap-content slot collapses to zero width —
+  # i.e. the component becomes invisible. Use {.fixed} or {FILL} for those.
+  # 
+  # @!attribute [r] mode
+  #   @return [Symbol] `:fill`, `:wrap_content` or `:fixed`.
+  # @!attribute [r] amount
+  #   @return [Integer, nil] the cell count for `:fixed`; `nil` otherwise.
+  class Sizing
+    FILL: Sizing
+    WRAP_CONTENT: Sizing
+
+    # _@param_ `amount` — the number of cells to occupy; 0 or greater.
+    # 
+    # _@return_ — a fixed-size policy.
+    def self.fixed: (Integer amount) -> Sizing
+
+    # Resolves one dimension of a slot.
+    # 
+    # _@param_ `available` — cells the slot offers; 0 or greater.
+    # 
+    # _@param_ `content` — the component's natural extent on this axis (one dimension of its {Component#content_size}).
+    # 
+    # _@return_ — the resolved extent, always in `0..available`.
+    def resolve: (Integer available, Integer content) -> Integer
+
+    # _@return_ — `:fill`, `:wrap_content` or `:fixed`.
+    attr_reader mode: Symbol
+
+    # _@return_ — the cell count for `:fixed`; `nil` otherwise.
+    attr_reader amount: Integer?
+  end
+
   # A UI component which is positioned on the screen and draws characters into
   # its bounding rectangle (in {#repaint}).
   # 
@@ -636,13 +1030,19 @@ module Tuile
     # _@param_ `child` — the just-detached child.
     def on_child_removed: (Component child) -> void
 
-    # The {Size} big enough to show the entire component contents without
-    # scrolling. Plain components have no intrinsic content and report
-    # {Size::ZERO}; container/decorative components (e.g. {Label}, {List},
-    # {Layout}, {Window}) override this to fold in their content's natural
-    # extent. Used by callers like {Component::Popup} to auto-size to
-    # whatever content was assigned, regardless of its concrete type.
-    def content_size: () -> Size
+    # Called by a child component whose {#content_size} just changed (fired
+    # from the child's {#content_size=}). Does nothing by default — a plain
+    # container is not size-coupled to its children. Containers that derive
+    # their own natural size or child layout from a child's natural size
+    # override this (e.g. {Component::Window} re-lays-out a
+    # {Sizing::WRAP_CONTENT} footer and recomputes its own size from content;
+    # {Component::Popup} re-self-sizes). If the receiver's own
+    # {#content_size} changes as a consequence, its {#content_size=} notifies
+    # *its* parent in turn — so the event bubbles exactly as far as geometry
+    # keeps changing, and stops where it doesn't.
+    # 
+    # _@param_ `child` — the resized direct child.
+    def on_child_content_size_changed: (Component child) -> void
 
     # Where the hardware terminal cursor should sit when this component is the
     # cursor owner. Returns `nil` to indicate the cursor should be hidden. The
@@ -695,6 +1095,35 @@ module Tuile
     # no parent.
     attr_accessor parent: Component?
 
+    # Called on every attached component (pre-order, popups included) when
+    # {Screen#theme} changes — at {Screen#theme=} / {Screen#theme_def=}
+    # assignment and on OS appearance flips.
+    # 
+    # Built-in components read {Screen#theme} at paint time, so their accents
+    # restyle automatically; this hook exists for *content* whose colors the
+    # app baked in from the old theme — a {Label#text} / {List#lines} /
+    # {TextView#text} {StyledString} styled with `theme[:accent]` and the
+    # like. Only the app knows which of its colors were theme-derived (as
+    # opposed to inherent to the data, e.g. log-level colors), so it rebuilds
+    # them here, re-running the same code that rendered them initially.
+    # 
+    # Runs on the UI thread; {Screen#theme} already returns the new theme.
+    # Mutating content (`text=`, `lines=`, …) is safe — repaint coalesces per
+    # event-loop tick. Do not assign {Screen#theme=} from inside the hook.
+    # 
+    # Subclasses overriding this should call `super` so an assigned
+    # {#on_theme_changed=} listener keeps firing.
+    attr_accessor on_theme_changed: Proc?
+
+    # The {Size} big enough to show the entire component contents without
+    # scrolling. Plain components have no intrinsic content and report
+    # {Size::ZERO}; content-bearing components (e.g. {Label}, {List},
+    # {TextView}, {Window}) maintain it eagerly via {#content_size=} from
+    # their mutators, so reads are O(1). Used by callers like
+    # {Component::Popup} to auto-size to whatever content was assigned,
+    # regardless of its concrete type, and by {Sizing::WRAP_CONTENT} slots.
+    attr_accessor content_size: Size
+
     # A scrollable list of items with cursor support.
     # 
     # Items are modeled as {StyledString}s and painted directly into the
@@ -707,11 +1136,9 @@ module Tuile
     # 
     # 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. The cursor highlight overlays a dark background
-    # while preserving each span's foreground color.
+    # list automatically. The cursor highlight overlays
+    # {Theme#active_bg_color} while preserving each span's foreground color.
     class List < Component
-      CURSOR_BG: Integer
-
       def initialize: () -> void
 
       # Sets new lines. Each entry is coerced into a {StyledString} (a
@@ -750,8 +1177,6 @@ module Tuile
       # _@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
@@ -803,6 +1228,19 @@ module Tuile
       # is one, so the list snaps to the bottom on first paint.
       def on_width_changed: () -> void
 
+      # Natural size from scratch: longest line's display width plus the two
+      # single-space gutters {#pad_to_row} adds, × line count. An empty list
+      # is {Size::ZERO} (no gutters for no content).
+      def compute_content_size: () -> Size
+
+      # Incremental {#content_size} update for appends: folds just the
+      # appended lines into the running maximum, keeping {#add_lines}
+      # O(appended) instead of re-scanning the whole list (LogWindow appends
+      # a line per log statement).
+      # 
+      # _@param_ `appended` — the just-appended lines (already concatenated onto {@lines}).
+      def grow_content_size: (::Array[StyledString] appended) -> 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
@@ -1090,11 +1528,6 @@ module Tuile
     class Label < Component
       def initialize: () -> 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
@@ -1105,13 +1538,22 @@ module Tuile
 
       def on_width_changed: () -> void
 
+      # Natural size: longest hard-line's display width × number of hard
+      # lines. Computed on the *unclipped* text — sizing is intrinsic to the
+      # content, not the viewport. Empty text yields {Size::ZERO}.
+      def compute_content_size: () -> Size
+
       # 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.
+      # last text line. When {#bg} is set, every produced line (and the
+      # blank row) has the bg applied uniformly.
       def update_clipped_lines: () -> void
 
+      # _@param_ `line`
+      def apply_bg: (StyledString line) -> StyledString
+
       # _@param_ `line`
       # 
       # _@param_ `width`
@@ -1120,6 +1562,11 @@ module Tuile
       # _@return_ — the current text. Defaults to an empty
       # {StyledString}.
       attr_accessor text: (StyledString | String)?
+
+      # _@return_ — background color applied uniformly across every
+      # painted row (including padding past the text). `nil` (default)
+      # leaves whatever bg the text's own styling carries.
+      attr_accessor bg: (Color | Symbol | Integer | ::Array[Integer])?
     end
 
     # A modal overlay that wraps any {Component} as its content. Popup itself
@@ -1182,6 +1629,14 @@ module Tuile
       # _@param_ `new_content`
       def content=: (Component? new_content) -> void
 
+      # Re-sizes (and recenters, when open) whenever the wrapped content's
+      # natural size changes — e.g. a {Label}'s `text=`, a {List}'s
+      # `add_line`, or a nested {Window} whose own content grew (the window
+      # recomputes its {Component#content_size} and the change bubbles here).
+      # 
+      # _@param_ `_child`
+      def on_child_content_size_changed: (Component _child) -> void
+
       # Hint for the status bar: own "q Close" plus the wrapped content's hint.
       def keyboard_hint: () -> String
 
@@ -1229,10 +1684,6 @@ module Tuile
 
       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
 
@@ -1241,6 +1692,9 @@ module Tuile
 
       def repaint: () -> void
 
+      # Natural width is `caption.length + 4` to fit `[ caption ]`; height 1.
+      def natural_size: () -> Size
+
       # _@return_ — the button's label.
       attr_accessor caption: String
 
@@ -1335,11 +1789,21 @@ module Tuile
       # _@param_ `value`
       def scrollbar=: (bool value) -> void
 
-      # _@return_ — the size needed to fit the window's content, footer
-      # (width only — footer overlays the bottom border), and caption,
-      # plus the 2-character border. Returns {Size}`.new(2, 2)` when the
-      # window has no content, footer, or caption.
-      def content_size: () -> Size
+      # Sets the new content. Also recomputes the window's natural size.
+      # 
+      # _@param_ `new_content`
+      def content=: (Component? new_content) -> void
+
+      # Re-lays-out a {Sizing::WRAP_CONTENT} footer when the footer's natural
+      # size changes, and folds a content resize into the window's own
+      # natural size (whose change then bubbles to the window's parent — e.g.
+      # a {Popup} re-self-sizes). The footer deliberately does *not*
+      # participate in the window's {#content_size}: it is decoration
+      # overlaying the border, and must not drive the window's size — if it
+      # doesn't fit, it is clipped to the inner width.
+      # 
+      # _@param_ `child`
+      def on_child_content_size_changed: (Component child) -> void
 
       # Fully repaints the window: both frame and contents.
       # 
@@ -1373,6 +1837,17 @@ module Tuile
       # _@param_ `caption`
       def build_frame: (String caption) -> String
 
+      # Recomputes the window's natural size: content's natural size (or the
+      # caption, whichever is wider) plus the 2-character border. The footer
+      # is deliberately excluded — see {#on_child_content_size_changed}. A
+      # window with no content or caption sizes to `Size.new(2, 2)` (bare
+      # border).
+      def update_content_size: () -> void
+
+      # Positions the footer over the bottom border row, with its width
+      # resolved by {#footer_sizing} against the inner width. A
+      # {Sizing::WRAP_CONTENT} footer with zero natural width gets an empty
+      # rect — i.e. it is invisible, as if never assigned.
       def layout_footer: () -> void
 
       def on_focus: () -> void
@@ -1381,6 +1856,11 @@ module Tuile
       # row.
       attr_accessor footer: Component?
 
+      # _@return_ — how the footer's width is computed from the window's
+      # inner width; defaults to {Sizing::FILL} (the footer spans the full
+      # inner width). The footer's height is always 1 (the border row).
+      attr_accessor footer_sizing: Sizing
+
       # _@return_ — the current caption, empty by default.
       attr_accessor caption: String
     end
@@ -1402,9 +1882,6 @@ module Tuile
     # plain `<textarea>` or text editor. A future `on_enter`/`on_submit`
     # callback may opt out of that by consuming Enter instead.
     class TextArea < Tuile::Component::TextInput
-      ACTIVE_BG_SGR: String
-      INACTIVE_BG_SGR: String
-
       def initialize: () -> void
 
       def cursor_position: () -> Point?
@@ -1513,9 +1990,27 @@ module Tuile
       # honored); a `StyledString` is used as-is; `nil` is coerced to an
       # empty {StyledString}.
       # 
+      # Detaches every existing {Region} (including the original default)
+      # and installs a fresh internal default region that owns all the new
+      # hard lines. Any handle the caller was holding becomes detached and
+      # raises on use — see {Region#attached?}. The no-op short-circuit
+      # (matching value, same {StyledString}) preserves existing regions.
+      # 
       # _@param_ `value`
       def text=: ((String | StyledString)? value) -> void
 
+      # Creates a new empty {Region} at the spatial tail of the document
+      # and returns its handle. Subsequent {#append} / {#<<} / {#add_line}
+      # calls route through this new region (since it is now the spatial
+      # tail). Earlier regions keep their content and their handles stay
+      # valid; their {Region#range} shifts as later regions grow.
+      # 
+      # Apps streaming logically-distinct sections (e.g. an LLM's "thinking"
+      # vs. "assistant" output) create one region per section, hold the
+      # handles, and call `region.append` / `region.text=` directly when
+      # they need to grow or rewrite an earlier section.
+      def create_region: () -> Region
+
       # _@return_ — true iff {#text} is empty (no hard lines).
       def empty?: () -> bool
 
@@ -1568,6 +2063,56 @@ module Tuile
       # _@param_ `n` — number of hard lines to drop; must be >= 0.
       def remove_last_n_lines: (Integer n) -> void
 
+      # Replaces a contiguous range of hard lines with the parsed content
+      # of `str`. The replacement is parsed exactly like {#text=} and
+      # {#append}: a {String} is run through {StyledString.parse} (so
+      # embedded ANSI is honored), a {StyledString} is used as-is, `nil`
+      # behaves like an empty replacement (the range is deleted). Embedded
+      # `"\n"` in the replacement produces multiple hard lines, so a single
+      # `replace` can grow or shrink the buffer.
+      # 
+      # `range` selects which hard lines to swap out:
+      # 
+      # - an `Integer` `n` is shorthand for `n..n` (replace one existing
+      #   line — `n` must be in `[0, hard-line count)`);
+      # - a non-empty `Range` of hard-line indices replaces those lines;
+      # - an empty `Range` (e.g. `2...2`, or the canonical end-insertion
+      #   `hard_lines.size...hard_lines.size`) is *insertion* at that
+      #   position — no lines are removed. {#insert} is a thin alias for
+      #   this case.
+      # 
+      # Endpoints must be non-negative integers; `begin` may equal
+      # `hard-line count` (insertion at the end), `end` may not exceed
+      # `hard-line count - 1`. `nil` endpoints (beginless / endless ranges)
+      # are not accepted.
+      # 
+      # Cost is roughly `O(from + length + new content)`: the splice
+      # updates only the affected slice of the physical-row buffer, using
+      # the per-hard-line wrap-count cache to locate the starting offset
+      # without re-wrapping preceding lines. Lines outside the splice are
+      # never re-wrapped. {#top_line} is clamped if the new line count
+      # puts it past the end; {#auto_scroll} pins it to the bottom as
+      # usual. The call is a no-op (no invalidation) when the parsed
+      # replacement equals the covered range (vacuously true for an empty
+      # range plus empty replacement, so `replace(n...n, "")` is a cheap
+      # no-op).
+      # 
+      # _@param_ `range` — hard-line indices to replace.
+      # 
+      # _@param_ `str` — replacement content.
+      def replace: ((::Range[untyped] | Integer) range, (String | StyledString)? str) -> void
+
+      # Inserts `str` at hard-line index `at`. Equivalent to
+      # `replace(at...at, str)` — a no-removal splice that grows the buffer
+      # by the parsed line count. `at == hard-line count` is allowed and
+      # appends at the end; for that case {#append} / {#add_line} are
+      # usually more idiomatic.
+      # 
+      # _@param_ `at` — 0-based hard-line index in `[0, hard-line count]`.
+      # 
+      # _@param_ `str` — content to insert.
+      def insert: (Integer at, (String | StyledString)? str) -> void
+
       # Clears the text. Equivalent to `text = ""`.
       def clear: () -> void
 
@@ -1593,41 +2138,164 @@ module Tuile
       # this hook.
       def on_width_changed: () -> void
 
+      # Validates and unpacks a {#replace}-style range argument into
+      # inclusive `[from, to]` line indices. An `Integer` `n` becomes
+      # `[n, n]` (which must point at an existing line — `Integer` is
+      # never insertion sugar). A `Range` is normalized for
+      # `exclude_end?`; `to == from - 1` is a valid empty range
+      # (insertion at `from`), and `from` may equal `size` for
+      # end-insertion. Shared by {#replace} and {Region#replace};
+      # `size` is the buffer or region line count, and `what` is the
+      # entity name woven into error messages.
+      # 
+      # _@param_ `range`
+      # 
+      # _@param_ `size`
+      # 
+      # _@param_ `what`
+      def normalize_replace_range: ((::Range[untyped] | Integer) range, ?Integer size, ?String what) -> [Integer, Integer]
+
+      # Hard-line index where `region` begins in {@hard_lines} — derived
+      # by summing the line counts of all regions that precede it.
+      # 
+      # _@param_ `region`
+      def region_start_index: (Region region) -> Integer
+
+      # Joined {StyledString} of the hard lines that `region` owns. Mirrors
+      # {#text} but scoped to one region.
+      # 
+      # _@param_ `region`
+      def text_for_region: (Region region) -> StyledString
+
+      # Replaces all of `region`'s hard lines with the parsed content of
+      # `value`. Symmetric with {#text=}, scoped to one region. Empty/nil
+      # content empties the region (no visible blank line). Works on
+      # already-empty regions (insertion at the region's position).
+      # 
+      # _@param_ `region`
+      # 
+      # _@param_ `value`
+      def set_region_text: (Region region, (String | StyledString)? value) -> void
+
+      # Region-scoped {#replace}. Validates `range` against
+      # `region.line_count`, translates region-relative indices to
+      # absolute buffer indices, splices, and updates the region's count.
+      # 
+      # _@param_ `region`
+      # 
+      # _@param_ `range`
+      # 
+      # _@param_ `str`
+      def replace_in_region: (Region region, (::Range[untyped] | Integer) range, (String | StyledString)? str) -> void
+
+      # Verbatim append into `region`.
+      # 
+      # _@param_ `region`
+      # 
+      # _@param_ `str`
+      def append_to_region: (Region region, (String | StyledString)? str) -> void
+
+      # Drops the last `n` hard lines from `region`'s tail via
+      # {#splice_hard_lines}. `n` is clamped to the region's current
+      # line count; callers guarantee `n > 0` and the region is
+      # non-empty (the {Region#remove_last_n_lines} guard handles the
+      # no-op cases).
+      # 
+      # _@param_ `region`
+      # 
+      # _@param_ `n`
+      def remove_last_n_from_region: (Region region, Integer n) -> void
+
+      # Drops `region` from {@regions}: its hard lines are removed via
+      # {#splice_hard_lines}, the handle is detached, and the always-one
+      # default is restored if the removal would have left zero regions.
+      # Skips the rewrap / invalidate work when the region was empty
+      # (the buffer didn't change), but always detaches.
+      # 
+      # _@param_ `region`
+      def remove_region: (Region region) -> void
+
+      # Adjusts region line counts after a {@hard_lines} splice that
+      # removed `removed_count` lines at index `from` and inserted
+      # `added_count` in their place. Two passes:
+      # 
+      # 1. Subtract each region's overlap with the removed range (uses
+      #    the original counts to compute positions). Remember the first
+      #    region that lost lines — that's the natural home for the
+      #    replacement content.
+      # 2. Credit `added_count` to that region. For pure insertions (no
+      #    removal), there's no "first overlapping region" to pick from;
+      #    walk regions and credit the latest one starting at `from` (the
+      #    boundary tiebreaker matches the spatial-tail-routing of
+      #    {#append}). Past-the-end inserts fall back to the tail region.
+      # 
+      # _@param_ `from`
+      # 
+      # _@param_ `removed_count`
+      # 
+      # _@param_ `added_count`
+      def update_region_counts: (Integer from, Integer removed_count, Integer added_count) -> void
+
       # _@return_ — number of visible lines.
       def viewport_lines: () -> Integer
 
       # _@return_ — the max value of {#top_line} for scroll-key clamping.
       def top_line_max: () -> Integer
 
-      # Recomputes {@physical_lines} for the current text and wrap width,
-      # pre-padding every line to `wrap_width` so {#paintable_line} is just
-      # a lookup + optional scrollbar-char append at paint time (and the
-      # rendered ANSI is cached on each line via {StyledString#to_ansi}'s
-      # memoization, so re-painting on scroll is near-free). Clamps
-      # {@top_line} if the new line count puts it out of range.
+      # Full rebuild of {@physical_lines} and {@hard_line_wrap_counts}
+      # from {@hard_lines}. Called when wrap width changes (which
+      # invalidates every cached row count) and from {#text=} (which
+      # replaces the whole logical model). Mid-buffer mutators splice
+      # incrementally via {#splice_hard_lines} and do *not* go through
+      # here. Clamps {@top_line} if the new line count puts it out of
+      # range.
       def rewrap: () -> void
 
-      # Wraps `hard_line` at `width` and appends the padded physical lines
-      # to {@physical_lines}. Empty hard lines (e.g. from a `"\n\n"` run)
-      # and degenerate `width <= 0` both emit a single {@blank_line} row,
-      # matching what `@text.wrap(width).map { |l| pad_to(l, width) }`
-      # would have produced for those cases.
+      # Wraps `hard_line` at `width` and returns the padded physical rows
+      # alongside the row count. Empty hard lines (e.g. from a `"\n\n"`
+      # run) and degenerate `width <= 0` both emit a single {@blank_line}
+      # row, matching what `@text.wrap(width).map { |l| pad_to(l, width) }`
+      # would have produced.
       # 
-      # _@param_ `hard_line` — one hard-broken line (no embedded `"\n"`).
+      # _@param_ `hard_line`
       # 
       # _@param_ `width`
-      def append_physical_lines: (StyledString hard_line, Integer width) -> void
+      def wrap_hard_line: (StyledString hard_line, Integer width) -> [::Array[StyledString], Integer]
 
-      # 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.
+      # Appends `hard_line` to the tail of {@hard_lines}, updating the
+      # wrap-count cache and {@physical_lines} in lockstep.
       # 
       # _@param_ `hard_line`
       # 
       # _@param_ `width`
-      def drop_physical_rows_for: (StyledString hard_line, Integer width) -> void
+      def push_hard_line: (StyledString hard_line, Integer width) -> void
+
+      # Pops the last hard line, the corresponding cache entry, and the
+      # physical rows that hard line contributed. Returns the popped
+      # hard line.
+      def pop_hard_line: () -> StyledString
+
+      # Splices `new_hard_lines` into the buffer in place of the `count`
+      # hard lines starting at index `from`. Updates {@hard_lines},
+      # {@hard_line_wrap_counts}, and {@physical_lines} consistently.
+      # The starting physical-row offset is computed in O(`from`) integer
+      # adds via the cache — no wraps of preceding hard lines. Wraps are
+      # done only for the new content, so total cost is
+      # `O(from + count + new_hard_lines.sum(&:display_width))`.
+      # 
+      # _@param_ `from`
+      # 
+      # _@param_ `count` — number of existing hard lines to remove.
+      # 
+      # _@param_ `new_hard_lines`
+      def splice_hard_lines: (Integer from, Integer count, ::Array[StyledString] new_hard_lines) -> void
+
+      # _@param_ `idx`
+      # 
+      # _@return_ — the {@physical_lines} index where the hard line
+      # at {@hard_lines}`[idx]` starts. O(`idx`) integer adds via the
+      # wrap-count cache.
+      def phys_offset_at: (Integer idx) -> Integer
 
       # Rebuilds the joined {StyledString} from {@hard_lines}, inserting a
       # default-styled `"\n"` between hard lines. Called from the {#text}
@@ -1691,6 +2359,136 @@ module Tuile
       # `Size.new(0, 0)`. Maintained incrementally by {#text=} and
       # {#append}, so reads are O(1).
       attr_reader content_size: Size
+
+      # A logical section of a {TextView}'s text — a contiguous run of
+      # hard lines the app wants to address as a unit (e.g. an LLM's
+      # "thinking" output vs. its assistant message). The view always
+      # has at least one region, an internal default that owns whatever
+      # hard lines aren't claimed by an app-created region.
+      # 
+      # Apps don't construct regions directly; call {TextView#create_region}
+      # to get one. The handle stays valid as long as the region is
+      # attached — i.e. until {TextView#text=} (or {TextView#clear}) wipes
+      # the slate and installs a fresh internal default. Detached regions
+      # raise {RuntimeError} on every mutator and reader.
+      # 
+      # A region's position is derived from its sibling order and counts,
+      # so growing or shrinking an earlier region implicitly shifts the
+      # ranges of all later regions. Empty regions occupy zero rows but
+      # still hold a position in the sequence; `region.text = ""` collapses
+      # a region's visible footprint without detaching it. Pre-creating
+      # empty placeholder regions is supported and is the natural pattern
+      # for "I'll fill this in later" layouts.
+      class Region
+        # _@param_ `view` — the owning view (never `nil` at construction).
+        # 
+        # _@param_ `line_count` — number of hard lines this region owns.
+        def initialize: (TextView view, ?Integer line_count) -> void
+
+        # _@return_ — `true` while the region is owned by its
+        # {TextView}. Becomes `false` permanently once detached
+        # (typically by {TextView#text=} / {TextView#clear}).
+        def attached?: () -> bool
+
+        # _@return_ — true iff the region owns zero hard lines.
+        # Empty regions render nothing — they still hold a position in
+        # the sequence, so subsequent mutations route to them as usual.
+        def empty?: () -> bool
+
+        # _@return_ — the joined content of just this region's
+        # hard lines. Empty regions return {StyledString::EMPTY}.
+        def text: () -> StyledString
+
+        # Replaces all of this region's hard lines with the parsed content
+        # of `value`. Accepts the same inputs as {TextView#text=}; empty
+        # or `nil` content collapses the region to zero hard lines.
+        # 
+        # _@param_ `value`
+        def text=: ((String | StyledString)? value) -> void
+
+        # Verbatim append into this region's tail. Same semantics as
+        # {TextView#append} but scoped to the region: embedded `"\n"`
+        # creates new hard lines within the region, no-leading-newline
+        # input extends the region's last hard line. Empty / `nil` input
+        # is a no-op (but still raises when detached). When the region is
+        # the spatial tail of the view, this uses the incremental
+        # {TextView#append} path; mid-document regions splice the affected
+        # slice of the physical-row buffer (lines outside the region are
+        # not re-wrapped).
+        # 
+        # _@param_ `str`
+        def append: ((String | StyledString)? str) -> void
+
+        # _@return_ — the hard-line indices this region currently
+        # occupies — `start...(start + line_count)`. Empty regions
+        # return a degenerate exclusive range at their position (e.g.
+        # `5...5`). The result is computed on each call and so always
+        # reflects sibling mutations.
+        def range: () -> ::Range[untyped]
+
+        # Removes this region from its view. The region's hard lines (if
+        # any) are deleted from the buffer — subsequent regions' ranges
+        # shift up by `line_count` — and the handle detaches permanently.
+        # The view keeps its always-≥1-region invariant: if this was the
+        # only remaining region, a fresh internal default is installed
+        # (the app doesn't get a handle to it; call
+        # {TextView#create_region} again to start tracking).
+        # 
+        # Idempotent: calling `remove` on an already-detached region is a
+        # silent no-op (unlike the other mutators, which raise). This
+        # lets cleanup paths blindly call `remove` without first checking
+        # {#attached?}.
+        def remove: () -> void
+
+        # Appends `str` as a new entry in this region: starts a fresh
+        # hard line first (when the region is non-empty), then appends
+        # `str`. Scoped equivalent of {TextView#add_line}. On an empty
+        # region behaves like {#append}.
+        # 
+        # _@param_ `str`
+        def add_line: ((String | StyledString)? str) -> void
+
+        # Replaces a contiguous range of this region's hard lines with the
+        # parsed content of `str`. Region-scoped counterpart of
+        # {TextView#replace}: indices are 0-based **within the region**
+        # (so `replace(0, "x")` rewrites the region's first line, not
+        # the buffer's). Same range conventions apply — `Integer`,
+        # inclusive/exclusive `Range`, empty range as insertion at
+        # `begin`, and `begin == line_count` for end-insertion.
+        # 
+        # _@param_ `range` — region-relative hard-line indices.
+        # 
+        # _@param_ `str` — replacement content.
+        def replace: ((::Range[untyped] | Integer) range, (String | StyledString)? str) -> void
+
+        # Inserts `str` at region-relative hard-line index `at`.
+        # Equivalent to `replace(at...at, str)`. Region-scoped counterpart
+        # of {TextView#insert}; `at == line_count` is allowed and appends
+        # at the region's tail.
+        # 
+        # _@param_ `at` — region-relative index in `[0, line_count]`.
+        # 
+        # _@param_ `str`
+        def insert: (Integer at, (String | StyledString)? str) -> void
+
+        # Drops the last `n` hard lines from this region's tail.
+        # Subsequent regions' ranges shift up by the number actually
+        # dropped. `n` is clamped to {#line_count}, so passing a large
+        # `n` empties the region — the handle stays attached (use
+        # {#remove} when the goal is to drop the region itself).
+        # `n == 0` and an already-empty region are no-ops.
+        # 
+        # _@param_ `n`
+        def remove_last_n_lines: (Integer n) -> void
+
+        def detach!: () -> void
+
+        def check_attached: () -> void
+
+        # _@return_ — number of hard lines this region owns. Safe to
+        # read on a detached region (no error raised).
+        attr_accessor line_count: (Integer | untyped)
+      end
     end
 
     # Shows a log. Construct your logger pointed at a {LogWindow::IO} to route
@@ -1741,9 +2539,6 @@ module Tuile
     # positioned by {Screen} after each repaint cycle when this component is
     # focused; see {Component#cursor_position}.
     class TextField < Tuile::Component::TextInput
-      ACTIVE_BG_SGR: String
-      INACTIVE_BG_SGR: String
-
       def initialize: () -> void
 
       def cursor_position: () -> Point?
@@ -1818,9 +2613,6 @@ module Tuile
     #   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.
@@ -1837,6 +2629,16 @@ module Tuile
       # _@param_ `key`
       def handle_key: (String key) -> bool
 
+      # Renders `text` on the field's background well, looked up from the
+      # current {Screen#theme} at paint time: {Theme#active_bg} when this
+      # input is on the active (focus) chain, {Theme#input_bg} otherwise —
+      # visibly a field either way, distinctly highlighted when active.
+      # 
+      # _@param_ `text`
+      # 
+      # _@return_ — ANSI-rendered text.
+      def background: (String text) -> String
+
       # Input filter for {#text=}. Subclasses override to truncate or reject
       # invalid input. Default coerces to String.
       # 
@@ -2004,6 +2806,71 @@ module Tuile
     end
   end
 
+  # An app's theme definition: the {Theme} pair covering both terminal
+  # appearances. {Screen} keeps one at {Screen#theme_def} (defaulting to
+  # {DEFAULT}) and picks the member matching the detected background at
+  # startup and on every OS appearance flip (mode 2031) — so a custom
+  # definition survives the user toggling light/dark, where a bare
+  # {Screen#theme=} assignment would be replaced.
+  # 
+  #   APP_THEME = Tuile::ThemeDef.new(
+  #     dark:  Tuile::Theme::DARK.with(custom: { accent: Color::DARK_ORANGE }),
+  #     light: Tuile::Theme::LIGHT.with(custom: { accent: Color::DARK_ORANGE3 })
+  #   )
+  #   screen.theme_def = APP_THEME
+  # 
+  # Both members must declare the same {Theme#custom} key set. Without
+  # that, a token present only in one member would raise `KeyError` at
+  # the unpredictable moment the user flips OS appearance; checking here
+  # turns it into an immediate construction-time failure.
+  # 
+  # @!attribute [r] dark
+  #   The theme applied on dark terminal backgrounds.
+  #   @return [Theme]
+  # @!attribute [r] light
+  #   The theme applied on light terminal backgrounds.
+  #   @return [Theme]
+  class ThemeDef
+    DEFAULT: ThemeDef
+
+    # _@param_ `dark`
+    # 
+    # _@param_ `light`
+    def initialize: (dark: Theme, light: Theme) -> void
+
+    # The member for the given color scheme. Anything other than `:light`
+    # selects {#dark}, matching {TerminalBackground.detect}'s
+    # inconclusive-means-dark policy.
+    # 
+    # _@param_ `scheme` — `:dark` or `:light`.
+    def for: (Symbol scheme) -> Theme
+
+    # The definition newly-constructed {Screen}s start from (see
+    # {Screen#theme_def}); initially {DEFAULT}. Reassigning affects
+    # future screens only — an already-constructed screen keeps its
+    # definition until {Screen#theme_def=}.
+    # 
+    # Intended for test suites: production apps assign
+    # {Screen#theme_def=} once at startup, but component specs build a
+    # fresh {FakeScreen} per example, and a component reading a custom
+    # token (`theme[:accent]`) would `KeyError` against the built-in
+    # default. Point this at the app's definition once and every
+    # {Screen.fake} carries it:
+    # 
+    #   Tuile::ThemeDef.default = APP_THEME   # spec_helper.rb, once
+    #   before { Screen.fake }                # theme[:accent] resolves
+    def self.default: () -> ThemeDef
+
+    # _@param_ `theme_def`
+    def self.default=: (ThemeDef value) -> ThemeDef
+
+    # The theme applied on dark terminal backgrounds.
+    attr_reader dark: Theme
+
+    # The theme applied on light terminal backgrounds.
+    attr_reader light: Theme
+  end
+
   # An event queue. The idea is that all UI-related updates run from the thread
   # which runs the event queue only; this removes any need for locking and/or
   # need for thread-safety mechanisms.
@@ -2032,13 +2899,39 @@ module Tuile
     # Awaits until the event queue is empty (all events have been processed).
     def await_empty: () -> void
 
+    # Schedules `block` to fire on the event-loop thread roughly `fps` times
+    # per second, passing a 0-based monotonically increasing tick counter. Use
+    # it for animations (e.g. a `/-\|` spinner in a {Component::Label}) or
+    # periodic UI refresh from a background task.
+    # 
+    # The returned {Ticker} controls the schedule — call {Ticker#cancel} to
+    # stop it.
+    # 
+    # **Errors:** if `block` raises, the {Ticker} cancels itself and the
+    # exception flows through the normal event-loop error path — i.e.
+    # {Screen#on_error} for the default Tuile setup. Auto-cancel prevents a
+    # broken block from spamming `on_error` at the tick rate.
+    # 
+    # Tickers reuse `concurrent-ruby`'s shared timer thread
+    # ({Concurrent}.global_timer_set) — adding more tickers does not add more
+    # threads, just more work on the shared scheduler.
+    # 
+    # _@param_ `fps` — firings per second, must be positive. Fractional values are fine (`fps: 0.5` ⇒ one tick every two seconds).
+    def tick: (Numeric fps) ?{ (Integer tick) -> void } -> Ticker
+
     # Runs the event loop and blocks. Must be run from at most one thread at the
     # same time. Blocks until some thread calls {#stop}. Calls block for all
-    # events submitted via {#post}; the block is always called from the thread
-    # running this function.
+    # events; the block is always called from the thread running this function.
     # 
-    # Any exception raised by block is re-thrown, causing this function to
-    # terminate.
+    # Any exception raised by the block is re-thrown, causing this function to
+    # terminate. Wrap the block body in `rescue` if you want to handle errors
+    # without tearing down the loop — see {Screen#event_loop} for an example.
+    # 
+    # **Procs are yielded too.** A {#submit}ed block arrives as a `Proc` event;
+    # the consumer is responsible for invoking it (typically `event.call`).
+    # Yielding rather than dispatching inline means a raise inside the
+    # submitted block flows through the consumer's `rescue` like any other
+    # event-handler error, instead of bypassing it.
     def run_loop: () ?{ (Object event) -> void } -> void
 
     # _@return_ — true if this thread is running inside an event queue.
@@ -2103,12 +2996,65 @@ module Tuile
       attr_reader height: Integer
     end
 
+    # The terminal's color scheme changed — the user flipped the OS between
+    # light and dark appearance. Terminals supporting mode 2031 (kitty,
+    # foot, contour, ghostty, …) push the DSR-style report `\e[?997;1n`
+    # (dark) / `\e[?997;2n` (light) once {Screen#run_event_loop} enables
+    # the mode via {TerminalBackground::NOTIFY_ON}; the key thread parses
+    # it into this event and {Screen#event_loop} follows by assigning the
+    # matching {Theme}.
+    # 
+    # @!attribute [r] scheme
+    #   @return [Symbol] `:light` or `:dark`.
+    class ColorSchemeEvent
+      REPORT: Regexp
+
+      # _@param_ `key` — key read via {Keys.getkey}.
+      # 
+      # _@return_ — nil when `key` is not a
+      # color-scheme report.
+      def self.parse: (String key) -> ColorSchemeEvent?
+
+      # _@return_ — `:light` or `:dark`.
+      attr_reader scheme: Symbol
+    end
+
     # Emitted once when the queue is cleared, all messages are processed and the
     # event loop will block waiting for more messages. Perfect time for
     # repainting windows.
     class EmptyQueueEvent
       include Singleton
     end
+
+    # Handle returned by {EventQueue#tick}. Cancel a running ticker via
+    # {#cancel}.
+    # 
+    # Internally wraps a `Concurrent::TimerTask` whose firing posts a single
+    # submit-block to the owning {EventQueue}; the user's block therefore
+    # always runs on the event-loop thread and may freely mutate UI. If the
+    # user block raises, the Ticker auto-cancels and the exception is
+    # re-raised so it flows through the loop's normal error handling
+    # ({Screen#on_error} for the default Tuile setup).
+    class Ticker
+      # _@param_ `event_queue` — queue to dispatch tick calls onto.
+      # 
+      # _@param_ `fps` — firings per second (positive).
+      # 
+      # _@param_ `block` — called as `block.call(tick_count)` on each fire.
+      def initialize: (EventQueue event_queue, Numeric fps, Proc block) -> void
+
+      # _@return_ — true once {#cancel} has been called.
+      def cancelled?: () -> bool
+
+      # Stops the ticker. Idempotent and safe to call from any thread,
+      # including from inside the tick block. Any tick already queued on the
+      # event loop at the moment of cancellation is dropped before the user
+      # block runs.
+      def cancel: () -> void
+
+      # Runs on the event-loop thread.
+      def fire: () -> void
+    end
   end
 
   # Testing only — a screen which doesn't paint anything and pretends that the
@@ -2147,6 +3093,11 @@ module Tuile
 
     def invalidated_clear: () -> void
 
+    # No terminal probing in tests: skip {TerminalBackground.detect}
+    # (which would write an OSC 11 query to the test runner's TTY and
+    # steal its input) and pin the deterministic default.
+    def detect_scheme: () -> Symbol
+
     # _@return_ — whatever {#print} printed so far.
     attr_reader prints: ::Array[String]
   end
@@ -2456,16 +3407,16 @@ module Tuile
     # `underline`). Useful for row-level highlights — the new bg overlays
     # without dropping foreground colors the original styling carried.
     # 
-    # _@param_ `bg` — background color, in any of the forms accepted by {Style.new}. `nil` clears bg back to the terminal default.
-    def with_bg: ((Symbol | Integer | ::Array[Integer])? bg) -> StyledString
+    # _@param_ `bg` — background color, coerced via {Color.coerce}. `nil` clears bg back to the terminal default.
+    def with_bg: ((Color | Symbol | Integer | ::Array[Integer])? bg) -> StyledString
 
     # Returns a new {StyledString} with `fg` applied to every span, preserving
     # each span's text and other style attributes (`bg`, `bold`, `italic`,
     # `underline`). The new fg overlays without dropping background colors or
     # text attributes the original styling carried.
     # 
-    # _@param_ `fg` — foreground color, 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
+    # _@param_ `fg` — foreground color, coerced via {Color.coerce}. `nil` clears fg back to the terminal default.
+    def with_fg: ((Color | Symbol | Integer | ::Array[Integer])? fg) -> StyledString
 
     def inspect: () -> String
 
@@ -2481,10 +3432,11 @@ module Tuile
 
     # _@param_ `color`
     # 
-    # _@param_ `base` — base SGR code — 30 for fg, 40 for bg.
+    # _@param_ `target` — `:fg` or `:bg`.
     # 
-    # _@param_ `ext` — extended-color SGR code — 38 for fg, 48 for bg.
-    def color_codes: ((Symbol | Integer | ::Array[Integer])? color, base: Integer, ext: Integer) -> ::Array[Integer]
+    # _@return_ — SGR codes; `[39]` / `[49]` for the "default" reset
+    # when `color` is `nil`, otherwise delegated to {Color#sgr_codes}.
+    def color_codes: (Color? color, target: Symbol) -> ::Array[Integer]
 
     # _@param_ `start_or_range`
     # 
@@ -2537,18 +3489,16 @@ module Tuile
     class ParseError < Tuile::Error
     end
 
-    # A frozen value type describing the visual style of a {Span}.
-    # 
-    # `fg` and `bg` accept:
-    # - `nil` — the terminal default (SGR 39 / 49)
-    # - a symbol from {COLOR_SYMBOLS} — 8 standard + 8 bright ANSI colors
-    # - an Integer 0..255 — 256-color palette index (SGR 38;5;N / 48;5;N)
-    # - an `[r, g, b]` Array of three 0..255 Integers — 24-bit RGB
+    # A frozen value type describing the visual style of a {Span}. Colors are
+    # stored as {Color} instances (or `nil` for the terminal default); inputs
+    # to {.new} and {#merge} are coerced via {Color.coerce}, so the four
+    # accepted color forms — `nil`, Symbol, Integer 0..255, RGB Array — work
+    # transparently.
     # 
     # @!attribute [r] fg
-    #   @return [Symbol, Integer, Array<Integer>, nil]
+    #   @return [Color, nil]
     # @!attribute [r] bg
-    #   @return [Symbol, Integer, Array<Integer>, nil]
+    #   @return [Color, nil]
     # @!attribute [r] bold
     #   @return [Boolean]
     # @!attribute [r] italic
@@ -2556,12 +3506,11 @@ module Tuile
     # @!attribute [r] underline
     #   @return [Boolean]
     class Style
-      COLOR_SYMBOLS: ::Array[Symbol]
       DEFAULT: Style
 
-      # _@param_ `fg`
+      # _@param_ `fg` — coerced via {Color.coerce}.
       # 
-      # _@param_ `bg`
+      # _@param_ `bg` — coerced via {Color.coerce}.
       # 
       # _@param_ `bold`
       # 
@@ -2569,18 +3518,13 @@ module Tuile
       # 
       # _@param_ `underline`
       def self.new: (
-                      ?fg: (Symbol | Integer | ::Array[Integer])?,
-                      ?bg: (Symbol | Integer | ::Array[Integer])?,
+                      ?fg: (Color | Symbol | Integer | ::Array[Integer])?,
+                      ?bg: (Color | Symbol | Integer | ::Array[Integer])?,
                       ?bold: bool,
                       ?italic: bool,
                       ?underline: bool
                     ) -> Style
 
-      # _@param_ `color`
-      # 
-      # _@param_ `which`
-      def self.validate_color!: (Object color, Symbol which) -> void
-
       def default?: () -> bool
 
       # Returns a new {Style} with the given attributes overridden.
@@ -2588,9 +3532,9 @@ module Tuile
       # _@param_ `overrides`
       def merge: (**::Hash[Symbol, Object] overrides) -> Style
 
-      attr_reader fg: (Symbol | Integer | ::Array[Integer])?
+      attr_reader fg: Color?
 
-      attr_reader bg: (Symbol | Integer | ::Array[Integer])?
+      attr_reader bg: Color?
 
       attr_reader bold: bool
 
@@ -2656,6 +3600,8 @@ module Tuile
   # A "synchronous" event queue – no loop is run, submitted blocks are run right
   # away and submitted events are thrown away. Intended for testing only.
   class FakeEventQueue
+    def initialize: () -> void
+
     def locked?: () -> bool
 
     def stop: () -> void
@@ -2668,6 +3614,127 @@ module Tuile
 
     # _@param_ `event`
     def post: (Object event) -> void
+
+    # Mirrors {EventQueue#tick} but timeless: returns a {FakeTicker} that
+    # only fires when a test calls {#tick_once}. The `fps` argument is
+    # validated the same way the real queue validates it, then discarded —
+    # the fake has no clock, so frame cadence is up to the test.
+    # 
+    # _@param_ `fps` — firings per second, must be positive. Validated for parity with {EventQueue#tick}; otherwise unused.
+    def tick: (Numeric fps) ?{ (Integer tick) -> void } -> FakeTicker
+
+    # Test helper: fires every live ticker's user block once and prunes
+    # cancelled tickers. No-op when no tickers are registered. Pumps once
+    # per call regardless of any ticker's fps — the fake has no clock, so
+    # tests pump N frames by calling this N times.
+    def tick_once: () -> void
+
+    # Handle returned by {FakeEventQueue#tick}. Mirrors the public surface of
+    # {EventQueue::Ticker} (`cancel`, `cancelled?`) but does not auto-fire —
+    # the host {FakeEventQueue} drives firing via {FakeEventQueue#tick_once}.
+    class FakeTicker
+      # _@param_ `block` — called as `block.call(tick_count)` on each {#fire}.
+      def initialize: (Proc block) -> void
+
+      # _@return_ — true once {#cancel} has been called.
+      def cancelled?: () -> bool
+
+      # Marks the ticker cancelled. Idempotent. Subsequent {#fire} calls are
+      # no-ops; {FakeEventQueue#tick_once} also prunes the ticker on its next
+      # pass.
+      def cancel: () -> void
+
+      # Invokes the user block with the current tick counter, then advances.
+      # No-op when {#cancelled?}. Typically driven by
+      # {FakeEventQueue#tick_once}; safe to call directly from a test that
+      # wants to drive a single ticker.
+      def fire: () -> void
+    end
+  end
+
+  # Detects whether the terminal background is light or dark, so {Screen}
+  # can pick {Theme::LIGHT} or {Theme::DARK} automatically at startup.
+  # 
+  # Two mechanisms, in order of reliability:
+  # 
+  # 1. **OSC 11 query** — writes `ESC ] 11 ; ? BEL` to the terminal; modern
+  #    terminals (xterm, kitty, alacritty, wezterm, iTerm2, GNOME Terminal,
+  #    Windows Terminal) reply on stdin with the background color
+  #    (`\e]11;rgb:RRRR/GGGG/BBBB` + BEL or ST). The color's relative
+  #    luminance against a 0.5 threshold decides light vs dark. Terminals
+  #    that don't support the query simply never reply, so the read is
+  #    bounded by a short timeout.
+  # 2. **`COLORFGBG` env var** — rxvt/konsole export `"fg;bg"` ANSI palette
+  #    indices. Less reliable (stale across SSH/tmux, often unset); used
+  #    only when OSC 11 yields nothing.
+  # 
+  # **Timing matters**: the OSC 11 reply arrives on stdin, so the query
+  # must complete before {EventQueue#start_key_thread} owns stdin —
+  # otherwise the reply bytes get consumed as garbage keystrokes. {Screen}
+  # calls {.detect} from its constructor, which apps run before
+  # {Screen#run_event_loop}; don't call this after the event loop started.
+  module TerminalBackground
+    QUERY_TIMEOUT: Float
+    QUERY: String
+    REPLY: Regexp
+    NOTIFY_ON: String
+    NOTIFY_OFF: String
+
+    # Detects the terminal background. Queries OSC 11 when both `input`
+    # and `output` are TTYs, falling back to `COLORFGBG`.
+    # 
+    # _@param_ `input` — where the OSC 11 reply arrives (the TTY input).
+    # 
+    # _@param_ `output` — where the query is written (the TTY output).
+    # 
+    # _@param_ `env` — environment for the `COLORFGBG` fallback; defaults to `ENV` (which duck-types the `[]` lookup).
+    # 
+    # _@param_ `timeout` — max seconds to wait for the OSC 11 reply.
+    # 
+    # _@return_ — `:light`, `:dark`, or nil when undetectable.
+    def self.detect: (
+                       ?input: IO,
+                       ?output: IO,
+                       ?env: ::Hash[String, String],
+                       ?timeout: Numeric
+                     ) -> Symbol?
+
+    # Writes the OSC 11 query and classifies the reply. The whole
+    # exchange runs with `input` in raw mode: the reply has no trailing
+    # newline, so a canonical-mode read would block past the timeout,
+    # and echo would smear the reply bytes onto the screen.
+    # 
+    # _@param_ `input`
+    # 
+    # _@param_ `output`
+    # 
+    # _@param_ `timeout`
+    def self.query_osc11: (IO input, IO output, Numeric timeout) -> Symbol?
+
+    # Accumulates reply bytes until a BEL/ST terminator or the deadline.
+    # Terminals that don't support OSC 11 never reply — returning
+    # whatever arrived (usually nothing) lets the caller fail soft.
+    # 
+    # _@param_ `input`
+    # 
+    # _@param_ `timeout`
+    def self.read_reply: (IO input, Numeric timeout) -> String
+
+    # Relative luminance of the reported background, scaled per
+    # component hex width (xterm replies 4 digits per channel, others 2).
+    # 
+    # _@param_ `components` — three hex strings.
+    # 
+    # _@return_ — `:light` or `:dark`.
+    def self.classify: (::Array[String] components) -> Symbol
+
+    # `COLORFGBG` is `"fg;bg"` (rxvt sometimes `"fg;default;bg"`) with
+    # ANSI palette indices. White-ish backgrounds — 7 (white) and the
+    # bright range 9–15 — read as light; 0–6 and 8 as dark; anything
+    # else (missing, `"default"`, out of range) is inconclusive.
+    # 
+    # _@param_ `value`
+    def self.from_colorfgbg: (String? value) -> Symbol?
   end
 
   # A vertical scrollbar that computes which character to draw at each row.