tuile 0.5.0 → 0.7.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
@@ -135,6 +136,13 @@ module Tuile
     # _@param_ `point`
     def contains?: (Point point) -> bool
 
+    # _@param_ `other` — another rectangle.
+    # 
+    # _@return_ — true if `other` lies entirely within this rectangle.
+    # Uses the same half-open edges as {#contains?} (right/bottom exclusive).
+    # An {#empty? empty} `other` covers no cells, so it is trivially contained.
+    def contains_rect?: (Rect other) -> bool
+
     def size: () -> Size
 
     def top_left: () -> Point
@@ -197,6 +205,9 @@ module Tuile
   # 
   # 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}.
@@ -206,15 +217,26 @@ module Tuile
   # 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
@@ -223,6 +245,35 @@ module Tuile
     # _@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
 
@@ -268,6 +319,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.
@@ -386,7 +644,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
     # 
@@ -394,7 +652,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}.
@@ -414,6 +672,15 @@ module Tuile
     # _@param_ `window`
     def remove_popup: (Component::Popup window) -> void
 
+    # Invalidates the entire attached tree, forcing every component to repaint
+    # on the next cycle. Needed whenever something overdraws the scene without
+    # clipping and then exposes what was underneath — a closing popup
+    # ({#remove_popup}), or a popup that shrinks or moves so its new {#rect} no
+    # longer covers the cells it previously painted ({Component::Popup#rect=}).
+    # The popup-only fast path in {#repaint} can't clear those vacated cells on
+    # its own, so we accept the cost of a full repaint.
+    def needs_full_repaint: () -> void
+
     # Internal — use {Component::Popup#open?} instead.
     # 
     # _@param_ `window`
@@ -462,6 +729,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
@@ -487,10 +771,6 @@ module Tuile
     # starts. {#size} provides correct size of the terminal.
     def layout: () -> void
 
-    # Called after a popup is closed. Since a popup can cover any window,
-    # top-level component or other popups, we need to redraw everything.
-    def needs_full_repaint: () -> void
-
     # A key has been pressed on the keyboard. Handle it, or forward to active
     # window.
     # 
@@ -545,6 +825,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
 
@@ -566,6 +862,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}).
   # 
@@ -700,13 +1042,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
@@ -759,6 +1107,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
@@ -771,13 +1148,17 @@ 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
 
+      # _@return_ — whether {#auto_scroll} is currently tailing. True
+      # while the viewport sits at the last line; flips to false the moment
+      # the user scrolls up, and back to true once they scroll to the bottom
+      # again. Only consulted when {#auto_scroll} is enabled.
+      def following?: () -> bool
+
       # 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
@@ -814,8 +1195,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
@@ -867,6 +1246,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
@@ -935,6 +1327,10 @@ module Tuile
       # _@return_ — the max value of {#top_line}.
       def top_line_max: () -> Integer
 
+      # _@return_ — whether the viewport is pinned to the last line.
+      # Drives {#following?}: re-evaluated on every {#top_line=}.
+      def at_bottom?: () -> bool
+
       # _@return_ — the number of visible lines.
       def viewport_lines: () -> Integer
 
@@ -951,6 +1347,11 @@ module Tuile
       # which would leave `top_line` past the last item once a real rect
       # arrives. {#on_width_changed} re-runs this hook when the rect grows so
       # the snap-to-bottom intent is preserved.
+      # 
+      # Gated on {#following?}: once the user scrolls up off the bottom the
+      # cursor snap and viewport pin are both skipped, so reading older
+      # content is not interrupted by incoming lines. {#top_line=} re-arms
+      # `@follow` when the viewport returns to the bottom.
       def update_top_line_if_auto_scroll: () -> void
 
       # _@return_ — whether the scrollbar should be drawn right now.
@@ -1006,7 +1407,10 @@ module Tuile
       attr_accessor on_cursor_changed: Proc?
 
       # _@return_ — if true and a line is added or new content is set,
-      # auto-scrolls to the bottom.
+      # auto-scrolls to the bottom — but only while the viewport is already
+      # pinned to the last line (see {#following?}). Scroll up to read older
+      # content and appends stop yanking you back down; scroll back to the
+      # bottom and tailing resumes.
       attr_accessor auto_scroll: bool
 
       # _@return_ — top line of the viewport. 0 or positive.
@@ -1154,11 +1558,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
@@ -1169,6 +1568,11 @@ 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
@@ -1223,6 +1627,17 @@ module Tuile
 
       def focusable?: () -> bool
 
+      # Reassigns the popup's rect, escalating to a full scene repaint when an
+      # open popup shrinks or moves so its new rect no longer covers the cells
+      # it previously painted. A popup overdraws the scene without clipping and
+      # nothing clears underneath it, so {Screen#repaint}'s popup-only fast path
+      # would repaint into the new rect and leave the vacated cells showing
+      # stale content. When the new rect fully covers the old one (the popup
+      # only grew), the fast path is correct and the full repaint is skipped.
+      # 
+      # _@param_ `new_rect`
+      def rect=: (Rect new_rect) -> void
+
       # Mounts this popup on the {Screen}. Recomputes the popup's size from
       # the current content first, so reopening a popup whose content has
       # grown or shrunk while closed picks up the new size.
@@ -1255,6 +1670,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
 
@@ -1270,6 +1693,11 @@ module Tuile
 
       # Recompute width/height from {#content}'s natural size and recenter
       # if currently open. Called whenever content is (re)assigned.
+      # 
+      # Computes the final (centered) rect and assigns it in one step rather
+      # than positioning at the origin and then centering: the intermediate
+      # origin rect rarely covers the previous one, which would make
+      # {#rect=}'s shrink/move detection fire a full repaint on every resize.
       def update_rect: () -> void
 
       # _@param_ `event`
@@ -1277,9 +1705,6 @@ module Tuile
 
       def children: () -> ::Array[Component]
 
-      # _@param_ `rect`
-      def rect=: (Rect rect) -> void
-
       def on_focus: () -> void
     end
 
@@ -1302,10 +1727,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
 
@@ -1314,6 +1735,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
 
@@ -1408,11 +1832,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.
       # 
@@ -1446,6 +1880,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
@@ -1454,6 +1899,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
@@ -1475,9 +1925,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?
@@ -1581,6 +2028,12 @@ module Tuile
       # O(total spans).
       def text: () -> StyledString
 
+      # _@return_ — whether {#auto_scroll} is currently tailing. True
+      # while the viewport sits at the last line; flips to false the moment
+      # the user scrolls up, and back to true once they scroll to the bottom
+      # again. Only consulted when {#auto_scroll} is enabled.
+      def following?: () -> bool
+
       # 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
@@ -1912,8 +2365,16 @@ module Tuile
       # _@param_ `target` — desired top line; clamped to `[0, top_line_max]`.
       def move_top_line_to: (Integer target) -> void
 
+      # Gated on {#following?}: once the user scrolls up off the bottom the
+      # viewport pin is skipped, so reading older content is not interrupted
+      # by incoming lines. {#top_line=} re-arms `@follow` when the viewport
+      # returns to the bottom.
       def update_top_line_if_auto_scroll: () -> void
 
+      # _@return_ — whether the viewport is pinned to the last line.
+      # Drives {#following?}: re-evaluated on every {#top_line=}.
+      def at_bottom?: () -> bool
+
       def scrollbar_visible?: () -> bool
 
       # Pads `line` with trailing default-styled spaces out to `width` display
@@ -1946,7 +2407,10 @@ module Tuile
       attr_accessor scrollbar_visibility: Symbol
 
       # _@return_ — if true, mutating the text scrolls the viewport so
-      # the last line stays in view. Default `false`.
+      # the last line stays in view — but only while the viewport is already
+      # pinned to the last line (see {#following?}). Scroll up to read older
+      # content and appends stop yanking you back down; scroll back to the
+      # bottom and tailing resumes. Default `false`.
       attr_accessor auto_scroll: bool
 
       # _@return_ — longest hard-line's display width × number of hard
@@ -2135,9 +2599,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?
@@ -2212,9 +2673,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.
@@ -2231,6 +2689,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.
       # 
@@ -2398,6 +2866,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.
@@ -2523,6 +3056,29 @@ 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.
@@ -2597,6 +3153,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
@@ -2751,7 +3312,7 @@ module Tuile
 
   # 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
+  # `underline`, `strikethrough`). 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`:
@@ -2791,12 +3352,21 @@ module Tuile
   # 
   # ## Parser
   # 
-  # {.parse} is strict by design: it recognizes only the SGR codes
+  # {.parse} is strict by default: 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
+  # underline/strikethrough). Anything else — unmodeled attributes (dim, blink,
+  # reverse, 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.
+  # 
+  # Pass `lenient: true` to instead **discard** everything the parser can't
+  # model and keep going — recognized fg/bg/bold/italic/underline/strikethrough codes still
+  # apply, and any unmodeled SGR code, malformed extended color, non-SGR CSI
+  # (cursor moves, `\e[K`), OSC/DCS/string sequence, or stray escape is
+  # silently dropped. This is the mode for piping in colored output you don't
+  # control (e.g. `git --color` through a pager): "give me the colors, throw
+  # the rest away." It is lossy by design — `parse(x, lenient: true)` does not
+  # round-trip back to `x`.
   class StyledString
     EMPTY: StyledString
 
@@ -2816,7 +3386,9 @@ module Tuile
     # default-styled span.
     # 
     # _@param_ `input`
-    def self.parse: ((String | StyledString)? input) -> StyledString
+    # 
+    # _@param_ `lenient` — when true, unmodeled SGR codes and non-SGR escapes are discarded instead of raising — see {StyledString} "## Parser". Lossy: the result no longer round-trips to `input`.
+    def self.parse: ((String | StyledString)? input, ?lenient: bool) -> StyledString
 
     # _@param_ `spans`
     def initialize: (?::Array[Span] spans) -> void
@@ -2903,7 +3475,7 @@ module Tuile
 
     # 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
+    # `underline`, `strikethrough`). Useful for row-level highlights — the new bg overlays
     # without dropping foreground colors the original styling carried.
     # 
     # _@param_ `bg` — background color, coerced via {Color.coerce}. `nil` clears bg back to the terminal default.
@@ -2911,7 +3483,7 @@ module Tuile
 
     # 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
+    # `underline`, `strikethrough`). The new fg overlays without dropping background colors or
     # text attributes the original styling carried.
     # 
     # _@param_ `fg` — foreground color, coerced via {Color.coerce}. `nil` clears fg back to the terminal default.
@@ -3004,6 +3576,8 @@ module Tuile
     #   @return [Boolean]
     # @!attribute [r] underline
     #   @return [Boolean]
+    # @!attribute [r] strikethrough
+    #   @return [Boolean]
     class Style
       DEFAULT: Style
 
@@ -3016,12 +3590,15 @@ module Tuile
       # _@param_ `italic`
       # 
       # _@param_ `underline`
+      # 
+      # _@param_ `strikethrough`
       def self.new: (
                       ?fg: (Color | Symbol | Integer | ::Array[Integer])?,
                       ?bg: (Color | Symbol | Integer | ::Array[Integer])?,
                       ?bold: bool,
                       ?italic: bool,
-                      ?underline: bool
+                      ?underline: bool,
+                      ?strikethrough: bool
                     ) -> Style
 
       def default?: () -> bool
@@ -3040,6 +3617,8 @@ module Tuile
       attr_reader italic: bool
 
       attr_reader underline: bool
+
+      attr_reader strikethrough: bool
     end
 
     # A maximal run of text sharing a single {Style}. `text` is plain — it
@@ -3065,14 +3644,18 @@ module Tuile
     # @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}.
+    # current span and updates the running {Style}. In strict mode anything
+    # outside the supported SGR alphabet raises {ParseError}; in lenient mode
+    # it is consumed and discarded (see {StyledString} "## Parser").
     class Parser
       STANDARD_COLORS: ::Array[Symbol]
       BRIGHT_COLORS: ::Array[Symbol]
+      STRING_INTRODUCERS: ::Array[String]
 
       # _@param_ `input`
-      def initialize: (String input) -> void
+      # 
+      # _@param_ `lenient` — when true, discard unmodeled SGR codes and non-SGR escapes instead of raising {ParseError}.
+      def initialize: (String input, ?lenient: bool) -> void
 
       def parse: () -> StyledString
 
@@ -3080,6 +3663,27 @@ module Tuile
 
       def consume_escape: () -> void
 
+      # Consumes a CSI sequence (`\e[` already eaten). A well-formed SGR
+      # (`\e[...m` with numeric/`;` params and no intermediates) is applied;
+      # anything else is a non-SGR or malformed CSI — raises in strict mode,
+      # swallowed in lenient. Scans the full CSI grammar (parameter bytes
+      # `\x30-\x3F`, intermediate bytes `\x20-\x2F`, final byte) so lenient
+      # mode consumes the whole sequence even for private-marker forms like
+      # `\e[?25l`.
+      def consume_csi: () -> void
+
+      # Lenient-only: discards a non-CSI escape (`\e` and `intro` already
+      # eaten). OSC/DCS/string sequences run to their string terminator; an
+      # nF escape (`\e( B`) eats its intermediates plus one final byte; any
+      # other Fe/Fp/Fs escape was complete in `intro` alone.
+      # 
+      # _@param_ `intro` — the byte after `\e` (never `"["`).
+      def consume_non_csi: (String intro) -> void
+
+      # Lenient-only: swallows an OSC/DCS/string-sequence payload up to and
+      # including its terminator (BEL, or ST `\e\\`), or to EOS if unterminated.
+      def consume_string_sequence: () -> void
+
       # _@param_ `params_str`
       def apply_sgr: (String params_str) -> void
 
@@ -3089,7 +3693,11 @@ module Tuile
       # 
       # _@param_ `target` — either `:fg` or `:bg`.
       # 
-      # _@return_ — how many SGR codes were consumed (3 for 256-color, 5 for RGB).
+      # _@return_ — how many SGR codes were consumed. In lenient mode a
+      # malformed color is skipped rather than applied, but the same count is
+      # returned (3 for 256-color, 5 for RGB) so the running index advances
+      # past its operands; an unknown selector skips just `38`/`48` + the
+      # selector byte (2), letting the rest be reprocessed.
       def consume_extended_color: (::Array[Integer] codes, Integer index, Symbol target) -> Integer
 
       def flush: () -> void
@@ -3151,6 +3759,91 @@ module Tuile
     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.
   # 
   # Uses `█` for the handle (filled track) and `░` for the empty track. There