tuile 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23a6288632a551240d224975faee1f71d477bb1465126d70915950f67c187650
-  data.tar.gz: 33e26892d2a625e85d5d2f2fd058a04080ef12ea38825cb2f9727a346f36c6a2
+  metadata.gz: fdf4dfc626b692fdeeb9dabbcd08fe94a74045ae24340b24074d601856b87bf8
+  data.tar.gz: a38a8d8f04c53341a1bf6adfbf551209fc8e917f6957076bcf291bb4c2f7837f
 SHA512:
-  metadata.gz: 233960b007d8c81281e6726e605ab48e9bdc389399b796a4d9a19314e1be2bfab019a787ddc6ab8b421221010cb9402fdc102737fef085aaa326641b76275eed
-  data.tar.gz: 68b2425566e2a2586d686699df135a4a7fce835b0f2ca5f090204b3b82f6d3b6d7813375f9129e5256eea627be8df72e667694869d4ba475de55221c0db5ae8e
+  metadata.gz: ee942fd7bd9c9c35212f20ae78d043df5c2fe5c9dfb3e3ca5b1e3acd98a1dfd9d7708c5a8d481f49b690c50c56b8d9f81f771adb668937ae0b45e5244f84fd71
+  data.tar.gz: 2735212649ff50b35814125ce0d91043f91bba7e4a8c4aa4a35b730708f66473536e2c240c70f45197bd89ef36154694119c8dfa0c70527f28e8c6520419dcd5

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 ## [Unreleased]
 
+## [0.6.0] - 2026-06-07
+
+- Add `Tuile::Theme` — semantic color tokens for the accents built-in components paint (the list-cursor/focused-input highlight `active_bg_color`, the inactive input well `input_bg_color`, the active window border `active_border_color`, the status-bar `hint_color`), with `DARK`/`LIGHT` presets and rendering helpers (`#active_bg`, `#active_border`, `#input_bg`, `#hint`). The current theme lives at `Screen#theme`; assigning restyles the whole UI in a single invalidate-everything pass. Everything that isn't an accent keeps inheriting the terminal's own default fg/bg.
+- Auto-detect the light/dark terminal background at startup: `Screen.new` queries the terminal via OSC 11 (`COLORFGBG` fallback, dark when inconclusive) and picks `Theme::LIGHT`/`Theme::DARK` to match.
+- Follow OS light/dark appearance flips live via mode 2031 (kitty, foot, contour, ghostty, …): the screen re-picks the matching theme and repaints everything.
+- Add app-specific theme tokens: `Theme#custom` (`Hash{Symbol => Color}`), looked up fail-fast via `Theme#[]` (`KeyError` on typos) and rendered via the generic `#fg`/`#bg` helpers. Subclass `Theme` to add one semantic coloring function per custom token — `Data#with` preserves the subclass. Theme tokens are strictly `Color` instances; `Color` gains the `Color.palette`/`Color.rgb` named constructors.
+- Add `Tuile::ThemeDef` — an app's dark/light `Theme` pair. Assigning `Screen#theme_def=` is the durable way to theme an app: the screen picks the member matching the detected background at startup and on every appearance flip, where a bare `theme=` assignment is transient. Construction validates that both members declare the same custom key set.
+- Add `ThemeDef.default` — the definition newly-constructed screens start from (initially `ThemeDef::DEFAULT`). Reassign it once in `spec_helper.rb` and every `Screen.fake` carries the app's custom tokens, instead of repeating `theme_def=` in each `before` block.
+- Name the 256-color palette: a constant per standard xterm chart name for palette indices 16..255 (`Color::CADET_BLUE` is `Color.palette(72)`; `Color::DODGER_BLUE1`, `Color::GREY37`, …) — exact palette cells, no quantization, listed in `Color::PALETTE_NAMES`. Where the chart names several cells identically, the first cell wins the constant; indices 0..15 keep the symbolic `Color::RED`/`Color::BRIGHT_BLUE`/… constants, which respect the terminal's own scheme.
+- Add `Color.hex` — a 24-bit RGB color from a CSS-style hex string (`Color.hex("#333333") == Color.rgb(51, 51, 51)`; leading `#` optional, case-insensitive, 3-digit shorthand expands as in CSS). Alpha forms (`#rgba`/`#rrggbbaa`) are rejected — SGR has no alpha channel. `Color.coerce` stays string-free; `.hex` is the explicit entry point.
+- Add `Component#on_theme_changed` — fired pre-order across the attached tree on every theme change, so apps can rebuild styled content whose colors were derived from the old theme. Override it (calling `super`) or assign the `on_theme_changed=` proc.
+- Add `Tuile::Sizing` (`FILL` / `WRAP_CONTENT` / `Sizing.fixed(n)`) and `Window#footer_sizing` — the footer slot is sized per policy against the inner width; a `WRAP_CONTENT` footer re-lays-out live as its content changes. The footer is excluded from `Window#content_size`: it is decoration overlaying the border and must not drive window size.
+- `Component#content_size` is now maintained eagerly: content mutators assign via the protected `content_size=` setter, which fires `parent.on_child_content_size_changed(self)` only when the value actually changed. Fixes a `Popup` staleness — an open popup now re-sizes and recenters when its content grows.
+- **Breaking:** `rainbow` is no longer a runtime dependency (nothing under `lib/` uses it — `Theme`/`StyledString`/`Color` produce all SGR output). Apps that style text with Rainbow must add it to their own Gemfile.
+
+## [0.5.0] - 2026-05-21
+
+- Add `Tuile::Color` — a value type wrapping the four color forms ANSI understands (named Symbol, 256-color Integer, RGB Array, or `nil`). Pre-defined constants `Color::RED`, `Color::BRIGHT_BLUE`, … cover the 16 named ANSI colors; `Color.coerce` accepts raw forms transparently.
+- `Component::Label`: add `bg` accessor — applies a background color uniformly across every painted row (text, trailing pad, and blank rows past the last line). Accepts anything `Color.coerce` accepts.
+- Add `Component::TextView::Region` — opaque handle to a contiguous run of hard lines, so apps can stream into logical sections without tracking line indices across sibling mutations. Create with `view.create_region`; mutate via `region.append`/`#<<`/`#text=`/`#add_line`/`#remove_last_n_lines`/`#replace`/`#insert`/`#remove`. Detached handles raise on every reader / mutator (except `#remove`, which is idempotent). `view.text=` / `clear` detach all region handles and install a fresh internal default.
+- Add `Component::TextView#replace(range, str)` and `#insert(at, str)` for mid-buffer hard-line splices (Integer or Range, inclusive/exclusive end, empty range == insertion, `begin == hard-line count` valid for end-insertion).
+- `Component::TextView`: incremental wrap via a per-hard-line row-count cache — mid-buffer mutations now re-wrap only the affected slice instead of the whole buffer. Speeds up the LLM streaming path (mid-document `region.append`, tombstone-style `region.text=`, `view.replace`/`view.insert`). `view.append` on the spatial tail keeps its existing fast path; `view.text=` and `on_width_changed` still do a full rewrap (now rebuilding the cache too).
+- Add `EventQueue#tick(fps) { |n| ... }` returning a `Ticker` backed by `Concurrent::TimerTask`; fires on the event-loop thread with a 0-based monotonic counter. Intended for spinner animations, periodic refresh, or surfacing background-task progress. Auto-cancels on raise.
+- Add `FakeEventQueue#tick` and `FakeTicker` — synchronous test double that drives ticks deterministically.
+- **Breaking:** `StyledString::Style#fg` and `#bg` now return `Color` (or `nil`) instead of the raw `Symbol`/`Integer`/`Array`. `Style.new` and `#merge` continue to accept the raw forms via `Color.coerce`.
+- **Breaking:** Remove `StyledString::Style::COLOR_SYMBOLS` — moved to `Color::COLOR_SYMBOLS`.
+- **Breaking:** `EventQueue#run_loop` now yields submitted `Proc` events to its consumer block instead of dispatching them inline, so a raise from a `submit{}` block is routed through `Screen#on_error` like any other event. Custom `run_loop` consumers must `call` Procs in their case statement.
+
 ## [0.4.0] - 2026-05-20
 
 - Add `Screen#register_global_shortcut` for app-level hotkeys; registered shortcuts surface in the status bar via `hint:`.

data/README.md

@@ -169,7 +169,7 @@ mechanism that handles it wins:
    ```ruby
    screen.register_global_shortcut(Tuile::Keys::CTRL_L,
                                    over_popups: true,
-                                   hint: "^L #{Rainbow('log').cadetblue}") do
+                                   hint: "^L #{screen.theme.hint('log')}") do
      log_popup.open
    end
    screen.unregister_global_shortcut(Tuile::Keys::CTRL_L)
@@ -230,11 +230,155 @@ replaces it, prefixed with `q Close`:
 ```ruby
 class FilterWindow < Tuile::Component::Window
   def keyboard_hint
-    "f #{Rainbow('filter').cadetblue}  Enter #{Rainbow('open').cadetblue}"
+    "f #{screen.theme.hint('filter')}  Enter #{screen.theme.hint('open')}"
   end
 end
 ```
 
+### Theming
+
+The accent colors built-in components paint with — the list-cursor /
+focused-input highlight, the inactive input "well", the active window
+border, the status-bar hint color — come from a `Tuile::Theme`, a frozen
+value type of semantic color tokens. The current theme lives at
+`screen.theme`.
+
+The theme is picked automatically when the screen is constructed:
+`Screen.new` queries the terminal's background color (OSC 11, with a
+`COLORFGBG` fallback) and selects `Theme::LIGHT` on light backgrounds,
+`Theme::DARK` (the colors Tuile has always used) otherwise. While the
+event loop runs, terminals supporting mode 2031 (kitty, foot, contour,
+ghostty, …) push appearance changes, and the screen follows OS
+light/dark flips live, repainting everything in the matching theme.
+Override it any time:
+
+```ruby
+screen.theme = Tuile::Theme::LIGHT
+# or tweak a single token (tokens are strict: `Color` instances only):
+screen.theme = Tuile::Theme::DARK.with(active_border_color: Tuile::Color::CYAN)
+```
+
+Note a bare `theme=` assignment is transient: the next OS appearance flip
+re-picks from the screen's `ThemeDef` and replaces it. To theme an app
+durably, see [App themes](#app-themes) below.
+
+The theme's primary API is its rendering helpers — `active_bg(text)`,
+`active_border(text)`, `input_bg(text)`, `hint(text)` — which return the
+text wrapped in the token's color:
+
+```ruby
+screen.theme.hint("quit")        # => "\e[38;5;109mquit\e[0m"
+screen.theme.active_bg("[ Ok ]") # => "\e[48;5;59m[ Ok ]\e[0m"
+```
+
+The raw colors are also readable via the `*_color` counterparts
+(`active_bg_color`, …) for span-aware styling with `StyledString`.
+
+Assigning a theme invalidates every component, so the whole UI restyles on
+the next repaint. One caveat: strings with colors already baked in (global
+shortcut `hint:`s, `Theme#hint` output you cached) don't restyle —
+rebuild them in `Component#on_theme_changed` (see
+[Reacting to theme changes](#reacting-to-theme-changes)).
+
+Everything that isn't an accent deliberately inherits the terminal's own
+default foreground/background, which already matches the user's terminal
+theme — so there is no global `bg`/`fg` token to configure.
+
+### App themes
+
+Your app's own colors belong in the theme too, so they restyle in the same
+invalidate-everything pass and stay legible on both terminal backgrounds.
+Beyond the built-in tokens, a theme carries app-specific tokens in
+`custom` — a `Hash{Symbol => Color}`. Look them up with `theme[:token]`
+(fail-fast: a typo raises `KeyError` instead of quietly painting a
+default) and render with the generic `fg` / `bg` helpers:
+
+```ruby
+theme = Tuile::Theme::DARK.with(custom: { accent: Tuile::Color::DARK_ORANGE })
+theme[:accent]             # => Color — e.g. for StyledString#with_fg
+theme.fg(:accent, "NEW")   # => "\e[38;5;208mNEW\e[0m"
+```
+
+`Color::DARK_ORANGE` is `Color.palette(208)` — the 256-color palette
+carries a constant per standard xterm chart name (`CADET_BLUE`,
+`DODGER_BLUE1`, `GREY37`, …; see `Color::PALETTE_NAMES`), so a theme
+declaration can say which color it means instead of citing a bare index.
+
+The recommended shape is a `Theme` subclass that implements one coloring
+function per custom token, mirroring the built-in helpers (`hint`,
+`active_bg`, …) — call sites then read `theme.added("+42")` instead of
+`theme.fg(:added, "+42")`. `Data#with` preserves the subclass, so an
+`AppTheme` stays an `AppTheme` through `with`:
+
+```ruby
+class AppTheme < Tuile::Theme
+  # one coloring function per custom token
+  def added(text)   = fg(:added, text)
+  def removed(text) = fg(:removed, text)
+end
+```
+
+Build both appearance variants and pair them in a `Tuile::ThemeDef`
+assigned to `screen.theme_def=`. This is the durable way to theme an app:
+the screen picks the member matching the detected background at startup
+and re-picks on every OS appearance flip, so your definition survives
+light/dark toggles where a bare `theme=` assignment would be replaced.
+`ThemeDef.new` enforces that both members declare the same custom key
+set — a token present in only one variant fails at construction instead
+of raising `KeyError` at the unpredictable moment the user flips
+appearance:
+
+```ruby
+APP_THEME = Tuile::ThemeDef.new(
+  dark:  AppTheme.new(**Tuile::Theme::DARK.to_h,
+                      custom: { added:   Tuile::Color::DARK_SEA_GREEN,
+                                removed: Tuile::Color::LIGHT_PINK3 }),
+  light: AppTheme.new(**Tuile::Theme::LIGHT.to_h,
+                      custom: { added:   Tuile::Color::SPRING_GREEN4,
+                                removed: Tuile::Color::INDIAN_RED })
+)
+screen.theme_def = APP_THEME
+```
+
+In tests, a fresh `Screen.fake` per example starts from the built-in
+definition, so a component reading `theme[:added]` would `KeyError`.
+Instead of repeating `Screen.instance.theme_def = APP_THEME` in every
+`before` block, point the construction-time default at your definition
+once, in `spec_helper.rb`:
+
+```ruby
+Tuile::ThemeDef.default = APP_THEME   # every Screen.fake now carries it
+```
+
+### Reacting to theme changes
+
+Built-in components read `screen.theme` at paint time, so their accents
+restyle automatically. Content you rendered yourself does not: a
+`StyledString` stored in `Label#text` / `List#lines` / `TextView#text`
+has its colors baked in at construction, and only your app knows which of
+those were theme-derived (as opposed to inherent to the data — log-level
+colors, say). `Component#on_theme_changed` fires on every attached
+component when the theme changes (assignment or appearance flip); rebuild
+theme-derived content there by re-running the code that rendered it
+initially. Consume it either way:
+
+```ruby
+# composition style — assembling stock components:
+label.on_theme_changed = -> { label.text = render_status_line }
+
+# subclass style — call `super` so an assigned listener keeps firing:
+class DiffView < Tuile::Component::TextView
+  def on_theme_changed
+    super
+    self.text = render_diff   # screen.theme already returns the new theme
+  end
+end
+```
+
+The hook runs on the UI thread and repaint coalesces per tick, so
+mutating content inside it is safe. Don't assign `screen.theme=` from
+inside the hook.
+
 ## Components
 
 All components live under `Tuile::Component::*`. Each one is documented below
@@ -244,11 +388,13 @@ YARD output (`bundle exec rake yard`).
 ### `Component::Label`
 
 Static text. No word-wrapping; long lines are clipped to `rect.width`. Lines
-may contain Rainbow ANSI formatting.
+may contain ANSI SGR formatting — theme helper output, a `StyledString`,
+or any SGR-emitting library (e.g. Rainbow, which is no longer a Tuile
+dependency — add it to your own Gemfile if you use it).
 
 ```ruby
 label = Tuile::Component::Label.new
-label.text = "Hello, #{Rainbow('world').green}!"
+label.text = "Hello, #{screen.theme.hint('world')}!"
 ```
 
 Key API: `text=`, `content_size`.

data/examples/file_commander.rb

@@ -14,6 +14,7 @@
 #
 # Press q or ESC to exit.
 
+require "rainbow"
 require "tuile"
 
 module FileCommanderExample
@@ -111,9 +112,9 @@ module FileCommanderExample
   # land in one place.
   class PaneWindow < Tuile::Component::Window
     def keyboard_hint
-      "Tab #{Rainbow("Switch").cadetblue}  " \
-        "Enter #{Rainbow("Open").cadetblue}  " \
-        "Bksp #{Rainbow("Up").cadetblue}"
+      "Tab #{screen.theme.hint("Switch")}  " \
+        "Enter #{screen.theme.hint("Open")}  " \
+        "Bksp #{screen.theme.hint("Up")}"
     end
   end
 

data/examples/sampler.rb

@@ -11,6 +11,7 @@
 #
 # Keys (global): q or ESC to quit.
 
+require "rainbow"
 require "tuile"
 
 module SamplerExample

data/lib/tuile/ansi.rb

@@ -2,9 +2,10 @@
 
 module Tuile
   # 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
     # SGR reset (`ESC [ 0 m`). Restores the terminal's default foreground,
     # background, and text attributes.

data/lib/tuile/color.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+module Tuile
+  # 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
+    # Symbolic color names. Order is significant: indices 0..7 map to the
+    # standard ANSI colors (SGR 30..37 fg / 40..47 bg); indices 8..15 map to
+    # bright variants (SGR 90..97 / 100..107).
+    # @return [Array<Symbol>]
+    COLOR_SYMBOLS = %i[
+      black red green yellow blue magenta cyan white
+      bright_black bright_red bright_green bright_yellow
+      bright_blue bright_magenta bright_cyan bright_white
+    ].freeze
+
+    # 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 [Color, Symbol, Integer, Array<Integer>, nil]
+    # @return [Color, nil]
+    # @raise [ArgumentError] when `value` is not one of the accepted forms.
+    def self.coerce(value)
+      case value
+      when nil, Color then value
+      else new(value)
+      end
+    end
+
+    # 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 [Integer] palette index, 0..255.
+    # @return [Color]
+    # @raise [ArgumentError] when `index` is not an Integer in 0..255.
+    def self.palette(index)
+      raise ArgumentError, "invalid palette index: #{index.inspect}" unless index.is_a?(Integer)
+
+      new(index)
+    end
+
+    # 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 [Integer] 0..255.
+    # @param green [Integer] 0..255.
+    # @param blue [Integer] 0..255.
+    # @return [Color]
+    # @raise [ArgumentError] when a channel is not an Integer in 0..255.
+    def self.rgb(red, green, blue)
+      new([red, green, blue])
+    end
+
+    # 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 [String] e.g. `"#333333"`, `"5F9EA0"`, `"#333"`.
+    # @return [Color] same value form as {.rgb} — `Color.hex("#333") ==
+    #   Color.rgb(51, 51, 51)`.
+    # @raise [ArgumentError] when `string` is not 3 or 6 hex digits with
+    #   an optional leading `#`.
+    def self.hex(string)
+      digits = string.delete_prefix("#") if string.is_a?(String)
+      raise ArgumentError, "invalid hex color: #{string.inspect}" unless digits&.match?(/\A(\h{3}|\h{6})\z/)
+
+      digits = digits.gsub(/\h/) { |d| d * 2 } if digits.length == 3
+      new(digits.scan(/\h{2}/).map { |channel| channel.to_i(16) })
+    end
+
+    # @param value [Symbol, Integer, Array<Integer>] see class-level docs for
+    #   the three accepted forms.
+    # @raise [ArgumentError] when `value` is not one of the accepted forms.
+    def initialize(value)
+      unless COLOR_SYMBOLS.include?(value) ||
+             (value.is_a?(Integer) && value.between?(0, 255)) ||
+             (value.is_a?(Array) && value.length == 3 &&
+              value.all? { |v| v.is_a?(Integer) && v.between?(0, 255) })
+        raise ArgumentError, "invalid color: #{value.inspect}"
+      end
+
+      @value = value.is_a?(Array) ? value.dup.freeze : value
+      freeze
+    end
+
+    # The underlying raw representation — a Symbol, Integer, or frozen
+    # Array<Integer>.
+    # @return [Symbol, Integer, Array<Integer>]
+    attr_reader :value
+
+    # 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 [Symbol] `:fg` or `:bg`.
+    # @return [Array<Integer>]
+    # @raise [ArgumentError] when `target` is neither `:fg` nor `:bg`.
+    def sgr_codes(target = :fg)
+      base, ext = case target
+                  when :fg then [30, 38]
+                  when :bg then [40, 48]
+                  else raise ArgumentError, "target must be :fg or :bg, got #{target.inspect}"
+                  end
+      case @value
+      when Symbol
+        idx = COLOR_SYMBOLS.index(@value)
+        idx < 8 ? [base + idx] : [base + 60 + (idx - 8)]
+      when Integer then [ext, 5, @value]
+      when Array then [ext, 2, *@value]
+      end
+    end
+
+    # 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 [Symbol] `:fg` or `:bg`.
+    # @return [String]
+    def to_ansi(target = :fg)
+      "\e[#{sgr_codes(target).join(";")}m"
+    end
+
+    # @param other [Object]
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(Color) && @value == other.value
+    end
+    alias eql? ==
+
+    # @return [Integer]
+    def hash
+      [self.class, @value].hash
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class.name} #{@value.inspect}>"
+    end
+
+    COLOR_SYMBOLS.each do |sym|
+      const_set(sym.upcase, new(sym))
+    end
+
+    # Names for the 256-color palette indices 16..255, from the standard
+    # xterm chart (<https://www.ditig.com/256-colors-cheat-sheet>). A constant
+    # per entry is pre-defined, an exact palette cell — no quantization:
+    # `Color::CADET_BLUE == Color.palette(72)`. The chart names some cells
+    # identically (`DeepSkyBlue4` covers 23, 24 *and* 25); the first
+    # occurrence wins the constant and the remaining cells stay reachable via
+    # {.palette}. Indices 0..15 are covered by the {COLOR_SYMBOLS} constants
+    # instead — the symbolic SGR form respects the user's terminal scheme,
+    # which a hard palette cell would not.
+    # @return [Hash{Symbol => Integer}]
+    PALETTE_NAMES = {
+      GREY0: 16, NAVY_BLUE: 17, DARK_BLUE: 18, BLUE3: 19, BLUE1: 21,
+      DARK_GREEN: 22, DEEP_SKY_BLUE4: 23, DODGER_BLUE3: 26, DODGER_BLUE2: 27,
+      GREEN4: 28, SPRING_GREEN4: 29, TURQUOISE4: 30, DEEP_SKY_BLUE3: 31,
+      DODGER_BLUE1: 33, GREEN3: 34, SPRING_GREEN3: 35, DARK_CYAN: 36,
+      LIGHT_SEA_GREEN: 37, DEEP_SKY_BLUE2: 38, DEEP_SKY_BLUE1: 39,
+      SPRING_GREEN2: 42, CYAN3: 43, DARK_TURQUOISE: 44, TURQUOISE2: 45,
+      GREEN1: 46, SPRING_GREEN1: 48, MEDIUM_SPRING_GREEN: 49, CYAN2: 50,
+      CYAN1: 51, DARK_RED: 52, DEEP_PINK4: 53, PURPLE4: 54, PURPLE3: 56,
+      BLUE_VIOLET: 57, ORANGE4: 58, GREY37: 59, MEDIUM_PURPLE4: 60,
+      SLATE_BLUE3: 61, ROYAL_BLUE1: 63, CHARTREUSE4: 64, DARK_SEA_GREEN4: 65,
+      PALE_TURQUOISE4: 66, STEEL_BLUE: 67, STEEL_BLUE3: 68,
+      CORNFLOWER_BLUE: 69, CHARTREUSE3: 70, CADET_BLUE: 72, SKY_BLUE3: 74,
+      STEEL_BLUE1: 75, PALE_GREEN3: 77, SEA_GREEN3: 78, AQUAMARINE3: 79,
+      MEDIUM_TURQUOISE: 80, CHARTREUSE2: 82, SEA_GREEN2: 83, SEA_GREEN1: 84,
+      AQUAMARINE1: 86, DARK_SLATE_GRAY2: 87, DARK_MAGENTA: 90, DARK_VIOLET: 92,
+      PURPLE: 93, LIGHT_PINK4: 95, PLUM4: 96, MEDIUM_PURPLE3: 97,
+      SLATE_BLUE1: 99, YELLOW4: 100, WHEAT4: 101, GREY53: 102,
+      LIGHT_SLATE_GREY: 103, MEDIUM_PURPLE: 104, LIGHT_SLATE_BLUE: 105,
+      DARK_OLIVE_GREEN3: 107, DARK_SEA_GREEN: 108, LIGHT_SKY_BLUE3: 109,
+      SKY_BLUE2: 111, DARK_SEA_GREEN3: 115, DARK_SLATE_GRAY3: 116,
+      SKY_BLUE1: 117, CHARTREUSE1: 118, LIGHT_GREEN: 119, PALE_GREEN1: 121,
+      DARK_SLATE_GRAY1: 123, RED3: 124, MEDIUM_VIOLET_RED: 126, MAGENTA3: 127,
+      DARK_ORANGE3: 130, INDIAN_RED: 131, HOT_PINK3: 132, MEDIUM_ORCHID3: 133,
+      MEDIUM_ORCHID: 134, MEDIUM_PURPLE2: 135, DARK_GOLDENROD: 136,
+      LIGHT_SALMON3: 137, ROSY_BROWN: 138, GREY63: 139, MEDIUM_PURPLE1: 141,
+      GOLD3: 142, DARK_KHAKI: 143, NAVAJO_WHITE3: 144, GREY69: 145,
+      LIGHT_STEEL_BLUE3: 146, LIGHT_STEEL_BLUE: 147, YELLOW3: 148,
+      DARK_SEA_GREEN2: 151, LIGHT_CYAN3: 152, LIGHT_SKY_BLUE1: 153,
+      GREEN_YELLOW: 154, DARK_OLIVE_GREEN2: 155, DARK_SEA_GREEN1: 158,
+      PALE_TURQUOISE1: 159, DEEP_PINK3: 161, MAGENTA2: 165, HOT_PINK2: 169,
+      ORCHID: 170, MEDIUM_ORCHID1: 171, ORANGE3: 172, LIGHT_PINK3: 174,
+      PINK3: 175, PLUM3: 176, VIOLET: 177, LIGHT_GOLDENROD3: 179, TAN: 180,
+      MISTY_ROSE3: 181, THISTLE3: 182, PLUM2: 183, KHAKI3: 185,
+      LIGHT_GOLDENROD2: 186, LIGHT_YELLOW3: 187, GREY84: 188,
+      LIGHT_STEEL_BLUE1: 189, YELLOW2: 190, DARK_OLIVE_GREEN1: 191,
+      HONEYDEW2: 194, LIGHT_CYAN1: 195, RED1: 196, DEEP_PINK2: 197,
+      DEEP_PINK1: 198, MAGENTA1: 201, ORANGE_RED1: 202, INDIAN_RED1: 203,
+      HOT_PINK: 205, DARK_ORANGE: 208, SALMON1: 209, LIGHT_CORAL: 210,
+      PALE_VIOLET_RED1: 211, ORCHID2: 212, ORCHID1: 213, ORANGE1: 214,
+      SANDY_BROWN: 215, LIGHT_SALMON1: 216, LIGHT_PINK1: 217, PINK1: 218,
+      PLUM1: 219, GOLD1: 220, NAVAJO_WHITE1: 223, MISTY_ROSE1: 224,
+      THISTLE1: 225, YELLOW1: 226, LIGHT_GOLDENROD1: 227, KHAKI1: 228,
+      WHEAT1: 229, CORNSILK1: 230, GREY100: 231, GREY3: 232, GREY7: 233,
+      GREY11: 234, GREY15: 235, GREY19: 236, GREY23: 237, GREY27: 238,
+      GREY30: 239, GREY35: 240, GREY39: 241, GREY42: 242, GREY46: 243,
+      GREY50: 244, GREY54: 245, GREY58: 246, GREY62: 247, GREY66: 248,
+      GREY70: 249, GREY74: 250, GREY78: 251, GREY82: 252, GREY85: 253,
+      GREY89: 254, GREY93: 255
+    }.freeze
+
+    PALETTE_NAMES.each do |name, index|
+      const_set(name, new(index))
+    end
+  end
+end

data/lib/tuile/component/button.rb

@@ -20,6 +20,7 @@ module Tuile
         super()
         @caption = caption.to_s
         @on_click = on_click
+        self.content_size = natural_size
       end
 
       # @return [String] the button's label.
@@ -38,16 +39,13 @@ module Tuile
 
         @caption = new_caption
         invalidate
+        self.content_size = natural_size
       end
 
       def focusable? = true
 
       def tab_stop? = true
 
-      # @return [Size] natural width is `caption.length + 4` to fit
-      #   `[ caption ]`; height is 1.
-      def content_size = Size.new(@caption.length + 4, 1)
-
       # @param key [String]
       # @return [Boolean]
       def handle_key(key)
@@ -78,9 +76,15 @@ module Tuile
         return if rect.empty?
 
         label = "[ #{@caption} ]"[0, rect.width]
-        styled = active? ? Rainbow(label).bg(:darkslategray) : label
+        styled = active? ? screen.theme.active_bg(label) : label
         screen.print TTY::Cursor.move_to(rect.left, rect.top), styled
       end
+
+      private
+
+      # Natural width is `caption.length + 4` to fit `[ caption ]`; height 1.
+      # @return [Size]
+      def natural_size = Size.new(@caption.length + 4, 1)
     end
   end
 end

data/lib/tuile/component/label.rb

@@ -11,6 +11,7 @@ module Tuile
       def initialize
         super
         @text = StyledString::EMPTY
+        @bg = nil
         @clipped_lines = []
         @blank_line = ""
       end
@@ -19,6 +20,11 @@ module Tuile
       #   {StyledString}.
       attr_reader :text
 
+      # @return [Color, nil] 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_reader :bg
+
       # Replaces the text. A `String` is parsed via {StyledString.parse}
       # (embedded ANSI is honored); a `StyledString` is used as-is; `nil` is
       # coerced to an empty {StyledString}. Lines wider than {#rect} are
@@ -30,23 +36,26 @@ module Tuile
         return if @text == new_text
 
         @text = new_text
-        @content_size = nil
         update_clipped_lines
         invalidate
+        self.content_size = compute_content_size
       end
 
-      # @return [Size] 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
-        @content_size ||=
-          if @text.empty?
-            Size::ZERO
-          else
-            hard_lines = @text.lines
-            width = hard_lines.map(&:display_width).max || 0
-            Size.new(width, hard_lines.size)
-          end
+      # Sets the background color. Coerced via {Color.coerce}, so a Symbol,
+      # Integer, Array, {Color}, or `nil` all work. `nil` clears the override
+      # — the label paints with whatever bg the text's own styling provides.
+      # Otherwise the bg overlays every span (including the trailing pad and
+      # blank rows past the last text line).
+      #
+      # @param value [Color, Symbol, Integer, Array<Integer>, nil]
+      # @return [void]
+      def bg=(value)
+        new_bg = Color.coerce(value)
+        return if @bg == new_bg
+
+        @bg = new_bg
+        update_clipped_lines
+        invalidate
       end
 
       # Paints the text into {#rect}.
@@ -75,16 +84,35 @@ module Tuile
 
       private
 
+      # 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}.
+      # @return [Size]
+      def compute_content_size
+        return Size::ZERO if @text.empty?
+
+        hard_lines = @text.lines
+        width = hard_lines.map(&:display_width).max || 0
+        Size.new(width, hard_lines.size)
+      end
+
       # 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.
       # @return [void]
       def update_clipped_lines
         width = rect.width.clamp(0, nil)
-        @blank_line = " " * width
-        @clipped_lines = @text.lines.map { |line| pad_to(line.ellipsize(width), width).to_ansi }
+        @blank_line = apply_bg(StyledString.plain(" " * width)).to_ansi
+        @clipped_lines = @text.lines.map { |line| apply_bg(pad_to(line.ellipsize(width), width)).to_ansi }
+      end
+
+      # @param line [StyledString]
+      # @return [StyledString]
+      def apply_bg(line)
+        @bg ? line.with_bg(@bg) : line
       end
 
       # @param line [StyledString]