tuile 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf132f33d9f0dfd061a502d0b974a9906436bbc585bf363eb0ec7d97a2b223ae
-  data.tar.gz: 2d91fe558079a4b5c43abd3818c3bb47cd50dc4ac3372c4afe011ef33dc97045
+  metadata.gz: fdf4dfc626b692fdeeb9dabbcd08fe94a74045ae24340b24074d601856b87bf8
+  data.tar.gz: a38a8d8f04c53341a1bf6adfbf551209fc8e917f6957076bcf291bb4c2f7837f
 SHA512:
-  metadata.gz: 8258e9e552143470a5642559f6db98e5292e14fa2fa52c30a06e26bf505e44ff1c889da73792bc262def396997861187d02d95d4189ced1f853ab91333e606b5
-  data.tar.gz: 99c03866f8d65ec2c6ca61381078b69616a3e23b3dada3cc11a3d4e2e1fc2973e1d15ac2ac0147e0e583edd20fae247e5be85ad974cf53e245a8cc109b3fe084
+  metadata.gz: ee942fd7bd9c9c35212f20ae78d043df5c2fe5c9dfb3e3ca5b1e3acd98a1dfd9d7708c5a8d481f49b690c50c56b8d9f81f771adb668937ae0b45e5244f84fd71
+  data.tar.gz: 2735212649ff50b35814125ce0d91043f91bba7e4a8c4aa4a35b730708f66473536e2c240c70f45197bd89ef36154694119c8dfa0c70527f28e8c6520419dcd5

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 ## [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.

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

@@ -10,6 +10,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}.
@@ -19,10 +22,20 @@ 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.
@@ -51,6 +64,50 @@ module Tuile
       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.
@@ -123,5 +180,70 @@ module Tuile
     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

@@ -36,9 +36,9 @@ module Tuile
         return if @text == new_text
 
         @text = new_text
-        @content_size = nil
         update_clipped_lines
         invalidate
+        self.content_size = compute_content_size
       end
 
       # Sets the background color. Coerced via {Color.coerce}, so a Symbol,
@@ -58,20 +58,6 @@ module Tuile
         invalidate
       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
-      end
-
       # Paints the text into {#rect}.
       #
       # Skips the {Component#repaint} default's auto-clear: every row is
@@ -98,6 +84,18 @@ 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

data/lib/tuile/component/list.rb

@@ -14,14 +14,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
-      # 256-color SGR index for the cursor-row background highlight. Matches
-      # what `Rainbow(...).bg(:darkslategray)` emits.
-      # @return [Integer]
-      CURSOR_BG = 59
-
       def initialize
         super
         @lines = []
@@ -135,11 +130,11 @@ module Tuile
         raise TypeError, "expected Array, got #{lines.inspect}" unless lines.is_a? Array
 
         @lines = parse_input_lines(lines)
-        @content_size = nil
         rebuild_padded_lines
         update_top_line_if_auto_scroll
         notify_cursor_changed
         invalidate
+        self.content_size = compute_content_size
       end
 
       # Without a block, returns the current lines. With a block, fully
@@ -181,20 +176,11 @@ module Tuile
         screen.check_locked
         new_lines = parse_input_lines(lines)
         @lines += new_lines
-        @content_size = nil
         @padded_lines += new_lines.map { |line| pad_to_row(line) }
         update_top_line_if_auto_scroll
         notify_cursor_changed
         invalidate
-      end
-
-      # @return [Size]
-      def content_size
-        @content_size ||= begin
-          content_w = @lines.map(&:display_width).max || 0
-          width = @lines.empty? ? 0 : content_w + 2
-          Size.new(width, @lines.size)
-        end
+        grow_content_size(new_lines)
       end
 
       def focusable? = true
@@ -508,6 +494,30 @@ module Tuile
 
       private
 
+      # 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).
+      # @return [Size]
+      def compute_content_size
+        content_w = @lines.map(&:display_width).max || 0
+        width = @lines.empty? ? 0 : content_w + 2
+        Size.new(width, @lines.size)
+      end
+
+      # 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 [Array<StyledString>] the just-appended lines
+      #   (already concatenated onto {@lines}).
+      # @return [void]
+      def grow_content_size(appended)
+        return if appended.empty?
+
+        appended_w = appended.map(&:display_width).max + 2
+        self.content_size = Size.new([content_size.width, appended_w].max, @lines.size)
+      end
+
       # 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
@@ -731,7 +741,7 @@ module Tuile
       def paintable_line(index, row_in_viewport, scrollbar)
         base = index < @lines.size ? @padded_lines[index] : @blank_padded
         is_cursor = (active? || @show_cursor_when_inactive) && index < @lines.size && @cursor.position == index
-        styled = is_cursor ? base.with_bg(CURSOR_BG) : base
+        styled = is_cursor ? base.with_bg(screen.theme.active_bg_color) : base
         out = styled.to_ansi
         out += scrollbar.scrollbar_char(row_in_viewport) if scrollbar
         out

data/lib/tuile/component/picker_window.rb

@@ -37,7 +37,7 @@ module Tuile
         @options = options.map { Option.new(it[0], it[1]) }
         @block = block
         list = Component::List.new
-        list.lines = @options.map { "#{it.key} #{Rainbow(it.caption).cadetblue}" }
+        list.lines = @options.map { "#{it.key} #{screen.theme.hint(it.caption)}" }
         list.cursor = Component::List::Cursor.new
         list.on_item_chosen = ->(index, _line) { select_option(@options[index].key) }
         self.content = list
@@ -65,7 +65,7 @@ module Tuile
 
       # @return [String]
       def keyboard_hint
-        @options.map { "#{it.key} #{Rainbow(it.caption).cadetblue}" }.join("  ")
+        @options.map { "#{it.key} #{screen.theme.hint(it.caption)}" }.join("  ")
       end
 
       # Opens a picker as a popup. Picking an option fires `block`, then

data/lib/tuile/component/popup.rb

@@ -81,10 +81,20 @@ module Tuile
         update_rect unless new_content.nil?
       end
 
+      # 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 [Component]
+      # @return [void]
+      def on_child_content_size_changed(_child)
+        update_rect
+      end
+
       # Hint for the status bar: own "q Close" plus the wrapped content's hint.
       # @return [String]
       def keyboard_hint
-        prefix = "q #{Rainbow("Close").cadetblue}"
+        prefix = "q #{screen.theme.hint("Close")}"
         child_hint = @content&.keyboard_hint.to_s
         child_hint.empty? ? prefix : "#{prefix}  #{child_hint}"
       end

data/lib/tuile/component/text_area.rb

@@ -70,7 +70,6 @@ module Tuile
       def repaint
         return if rect.empty?
 
-        bg = active? ? ACTIVE_BG_SGR : INACTIVE_BG_SGR
         rows = display_rows
         (0...rect.height).each do |screen_row|
           row_idx = screen_row + @top_display_row
@@ -81,7 +80,7 @@ module Tuile
                    chunk = @text[r[:start], r[:length]] || ""
                    chunk + (" " * (rect.width - r[:length]))
                  end
-          screen.print TTY::Cursor.move_to(rect.left, rect.top + screen_row), bg, line, Ansi::RESET
+          screen.print TTY::Cursor.move_to(rect.left, rect.top + screen_row), background(line)
         end
       end