tuile 0.8.0 → 0.10.0

data/lib/tuile/screen_pane.rb

@@ -23,7 +23,9 @@ module Tuile
       # cascaded to the first focusable child.
       @popup_prior_focus = {}
       @status_bar = Component::Label.new
-      @status_bar.parent = self
+      # Added first and never removed, so it is always the last child — which is
+      # the anchor `add_popup` inserts against.
+      add_child(@status_bar)
     end
 
     # @return [Component, nil] the tiled content component.
@@ -37,10 +39,6 @@ module Tuile
 
     def focusable? = false
 
-    # Children for tree traversal: content first, popups in stacking order,
-    # status bar last.
-    def children = [*[@content].compact, *@popups, @status_bar]
-
     # Replaces the tiled content. Wipes focus first (the new tree starts
     # fresh), detaches the old content, then attaches the new one and
     # re-lays out.
@@ -51,10 +49,9 @@ module Tuile
       return if @content == content
 
       screen.focused = nil
-      old = @content
-      old&.parent = nil
+      remove_child(@content) unless @content.nil?
       @content = content
-      content.parent = self
+      add_child(content, at: 0) # the tiled layer paints beneath everything else
       layout
     end
 
@@ -63,6 +60,12 @@ module Tuile
     # left wherever the caller positions it and does *not* take focus, so the
     # component that was focused keeps the cursor and keeps receiving keys —
     # the overlay floats above the content, driven from app code.
+    #
+    # The *whole subtree* is invalidated, not just the popup wrapper (which
+    # paints nothing on its own): a reopened popup may land on cells that the
+    # tiled content has since overpainted, and if its rect is unchanged from
+    # last time its content components won't re-invalidate themselves — so
+    # without this the popup's contents would stay blank on reopen.
     # @param window [Component::Popup]
     # @return [void]
     def add_popup(window)
@@ -71,12 +74,12 @@ module Tuile
 
       @popup_prior_focus[window] = screen.focused
       @popups << window
-      window.parent = self
+      add_child(window, at: @children.index(@status_bar))
       if window.modal?
         window.center
         screen.focused = window
       end
-      screen.invalidate(window)
+      window.on_tree { |c| screen.invalidate(c) }
     end
 
     # Removes a popup. If the popup held focus, focus shifts to the now-topmost
@@ -88,21 +91,35 @@ module Tuile
       raise Tuile::Error, "#{window} is not an open popup on this pane" unless @popups.delete(window)
 
       prior = @popup_prior_focus.delete(window)
-      # Detach first so the popup becomes its own root; then any prior
-      # pointing *inside* that popup is detectable via `p.root == window`.
-      window.parent = nil
-      # If any other popup recorded its prior focus inside the popup we're
-      # removing, forward it to *our* prior so chained closures still climb
-      # back to the original owner instead of stopping at a detached
-      # component.
-      @popup_prior_focus.transform_values! { |p| p && p.root == window ? prior : p }
-
       @removing_popup_prior = prior
-      on_child_removed(window)
+      remove_child(window)
+      # Runs after the detach, so a prior pointing *inside* the removed popup is
+      # detectable via `p.root == window`: forward it to *our* prior, so chained
+      # closures climb back to the original owner instead of stopping at a
+      # detached component.
+      @popup_prior_focus.transform_values! { |p| p && p.root == window ? prior : p }
     ensure
       @removing_popup_prior = nil
     end
 
+    # Unmounts everything: each child is detached — firing {Component#on_detached}
+    # down its subtree — and every slot is emptied. Terminal; the pane isn't
+    # reusable afterwards, and {Screen#close} is its only caller.
+    #
+    # Deliberately not named `close` ({Component::Popup#close} already means
+    # "remove *me* from the pane"), and deliberately not a generic
+    # `Component#remove_all_children`: a slot container calling that would empty
+    # `@children` while `#content` / `#footer` still pointed at detached
+    # components, which is the desync the tree API exists to prevent.
+    # @return [void]
+    def detach_all
+      screen.focused = nil # …so the focus repair in on_child_removed has nothing to do
+      children.dup.each { detach_child(_1) }
+      @content = nil
+      @popups.clear
+      @popup_prior_focus.clear
+    end
+
     # @param window [Component]
     # @return [Boolean] true if this pane currently hosts the popup.
     def has_popup?(window) = @popups.include?(window) # rubocop:disable Naming/PredicatePrefix
@@ -123,14 +140,16 @@ module Tuile
     end
 
     # Lays out content (full pane minus the bottom row) and the status bar
-    # (bottom row). Modal popups self-recenter via {Component::Popup#center};
-    # non-modal overlays keep the position their owner assigned.
+    # (bottom row). Each popup re-resolves its {Component::Popup#size} against
+    # the new screen via {Component::Popup#reposition} — so a {Fraction} size
+    # tracks resize — repositioning itself (modal popups recenter; non-modal
+    # overlays keep the top-left their owner assigned).
     # @return [void]
     def layout
       return if rect.empty?
 
       @content.rect = Rect.new(rect.left, rect.top, rect.width, [rect.height - 1, 0].max) unless @content.nil?
-      @popups.each { |p| p.center if p.modal? }
+      @popups.each(&:reposition)
       @status_bar.rect = Rect.new(rect.left, rect.top + rect.height - 1, rect.width, 1)
     end
 
@@ -138,34 +157,27 @@ module Tuile
     # @return [void]
     def repaint; end
 
-    # Dispatches a key in two phases, both scoped to the topmost *modal* popup
-    # (when one is open) or else the tiled {#content}. Non-modal overlays are
-    # never the scope: focus stays in the content beneath them, and the overlay
-    # is driven by app code (which forwards keys to it explicitly), so it
-    # doesn't appear in this path at all.
+    # Delivers a key to {Screen#focused}, then bubbles it up the focus chain —
+    # the first component whose `handle_key` returns true wins.
+    #
+    # Bubbling stops at the *scope* root: the topmost *modal* popup when one is
+    # open, else the tiled {#content}. Focus that is nil or sits outside the
+    # scope receives nothing, which is what keeps an open modal popup modal.
+    # Non-modal overlays are never the scope: focus stays in the content
+    # beneath them, and the overlay is driven by app code (which forwards keys
+    # to it explicitly), so it doesn't appear in this path at all.
     #
-    # 1. *Capture* — a {Component#key_shortcut} match anywhere in the scope
-    #    focuses that component and consumes the key. Suppressed while a
-    #    cursor-owner ({Screen#cursor_position}) is mid-edit, so typing into a
-    #    {Component::TextField} isn't hijacked by a sibling's shortcut.
-    # 2. *Delivery* — the key is handed to {Screen#focused} and bubbles up its
-    #    ancestor chain to the scope root; the first component to return true
-    #    wins. Focus that is nil or sits outside the scope receives nothing,
-    #    which is what keeps an open modal popup modal.
+    # Because an ancestor sees a key only after every descendant on the chain
+    # declined it, the scope root is the natural home for scope-wide fallbacks
+    # — a form's default button, or a layout's one-key jumps to its panes (a
+    # focused {Component::TextField} consumes the key first, so typing is never
+    # hijacked).
     # @param key [String]
     # @return [Boolean] true if the key was handled.
     def handle_key(key)
       scope = modal_popup || @content
       return false if scope.nil?
 
-      if screen.cursor_position.nil?
-        target = scope.find_shortcut_component(key)
-        unless target.nil?
-          screen.focused = target
-          return true
-        end
-      end
-
       bubble_key(key, scope)
     end
 

data/lib/tuile/styled_string.rb

@@ -3,14 +3,11 @@
 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`, `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`:
-  # slicing, wrapping, and concatenation operate on the structured spans, so
-  # they never have to "figure out what SGR state is active at column N" —
-  # the answer is just the containing span's `style`. The flip side is one
-  # extra type to construct (or parse) before doing styled-text math.
+  # `underline`, `strikethrough`). Spans are non-overlapping and fully tile
+  # the string — every character has exactly one resolved style, no overlay
+  # layers to merge, so the style at any column is just its span's `style`
+  # rather than a replay of the SGR state machine. The book's chapter 9 is
+  # the long-form *why* (spans vs. a `String` full of escape codes).
   #
   # ## Constructors
   #
@@ -34,30 +31,15 @@ module Tuile
   # ss.each_char_with_style { |ch, style| ... }
   # ```
   #
-  # ## Rendering
-  #
-  # - `#to_s` — plain text, no SGR.
-  # - `#to_ansi` — minimal-diff SGR rendering, ending with `\e[0m` only when
-  #   the last span carried a non-default style. Transitions to the default
-  #   style emit `\e[0m` (shorter than re-emitting every off-code).
-  #
   # ## Parser
   #
-  # {.parse} is strict by default: it recognizes only the SGR codes
-  # corresponding to {Style}'s supported attributes (fg/bg/bold/italic/
-  # 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`.
+  # {.parse} is strict by default — it recognizes only the SGR codes for
+  # {Style}'s attributes (fg/bg/bold/italic/underline/strikethrough) and
+  # raises {ParseError} on anything else, keeping the `parse(to_ansi(x)) == x`
+  # round-trip honest. Pass `lenient: true` to instead discard everything it
+  # can't model (unmodeled SGR, cursor moves, OSC/DCS, stray escapes) and keep
+  # only the recognized colors — lossy by design, for piping in colored output
+  # you don't control. See the book for the full rationale.
   class StyledString
     # Raised by {.parse} on malformed or unsupported escape sequences.
     class ParseError < Error; end
@@ -111,10 +93,6 @@ module Tuile
       # `""` when the styles are identical (nothing to do), and {Ansi::RESET}
       # (`\e[0m`, one code) when `other` is the default style — shorter than
       # turning each attribute off individually.
-      #
-      # Shared by {StyledString#to_ansi} (diffing span-to-span from the default
-      # style) and {Buffer}'s flush (diffing cell-to-cell against the style the
-      # terminal currently holds), so both emit identical minimal sequences.
       # @param other [Style] the style to transition to.
       # @return [String]
       def sgr_to(other)
@@ -419,6 +397,19 @@ module Tuile
       end
     end
 
+    # The framework's single emoji-width policy, passed to every
+    # `Unicode::DisplayWidth.of` call in Tuile.
+    #
+    # `:rgi` credits width 2 only to [RGI](https://www.unicode.org/reports/tr51/)
+    # sequences — the ones vendors actually ship a single glyph for — and *sums*
+    # the parts of anything else. That is the one setting never wrong in the
+    # dangerous direction: under-measuring lets a glyph overrun its cell, which
+    # shifts the rest of the row, desyncs the cursor and escapes the component's
+    # rect, while over-measuring leaves a blank column. `D-cluster-width` has the
+    # per-setting reasoning.
+    # @return [Symbol]
+    EMOJI_WIDTH = :rgi
+
     # @return [Array<Span>] the frozen, normalized span list — no empty-text
     #   entries, no two adjacent entries sharing a style.
     attr_reader :spans
@@ -430,10 +421,9 @@ module Tuile
 
     # Total display width in terminal columns, accounting for Unicode wide
     # characters (fullwidth CJK = 2 columns, combining marks = 0, etc.).
-    # Memoized — safe because spans are frozen and immutable.
     # @return [Integer]
     def display_width
-      @display_width ||= @spans.sum { |s| Unicode::DisplayWidth.of(s.text) }
+      @display_width ||= @spans.sum { |s| Unicode::DisplayWidth.of(s.text, emoji: EMOJI_WIDTH) }
     end
 
     # @return [Boolean]
@@ -450,7 +440,7 @@ module Tuile
     # emits `\e[0m` (one code) instead of the longer "turn each attribute
     # off" form. Always closes with `\e[0m` when the last span carried a
     # non-default style, so the styled run doesn't bleed into subsequent
-    # output. Memoized — safe because spans are frozen and immutable.
+    # output.
     # @return [String]
     def to_ansi
       @to_ansi ||= build_ansi
@@ -600,6 +590,24 @@ module Tuile
       self.class.new(@spans.map { |span| Span.new(text: span.text, style: span.style.merge(bg: bg)) })
     end
 
+    # Returns a copy with `bg` set **only on spans that have none**; a span with
+    # an explicit bg is left untouched. The fill-unset counterpart of {#with_bg}
+    # (which overrides every span) — it slides a background *under* the content,
+    # so a log line keeps its red error-level bg while its plain text picks up an
+    # inherited panel tint.
+    #
+    # @param bg [Color, Symbol, Integer, Array<Integer>, nil] background color,
+    #   coerced via {Color.coerce}. `nil` returns `self` unchanged.
+    # @return [StyledString]
+    def under_bg(bg)
+      return self if bg.nil?
+
+      bg = Color.coerce(bg)
+      self.class.new(@spans.map do |span|
+        span.style.bg.nil? ? Span.new(text: span.text, style: span.style.merge(bg: bg)) : span
+      end)
+    end
+
     # Returns a new {StyledString} with `fg` applied to every span, preserving
     # each span's text and other style attributes (`bg`, `bold`, `italic`,
     # `underline`, `strikethrough`). The new fg overlays without dropping background colors or
@@ -683,7 +691,7 @@ module Tuile
       out = []
       col = 0
       @spans.each do |span|
-        span_width = Unicode::DisplayWidth.of(span.text)
+        span_width = Unicode::DisplayWidth.of(span.text, emoji: EMOJI_WIDTH)
         span_end = col + span_width
 
         next col = span_end if span_end <= start
@@ -707,74 +715,92 @@ module Tuile
       return [hard_line] if hard_line.empty?
 
       result = []
-      line_chars = []
+      line_glyphs = []
       line_w = 0
 
-      tokenize_for_wrap(hard_line).each do |type, chars, w|
+      tokenize_for_wrap(hard_line).each do |type, glyphs, w|
         if type == :space
           if line_w.zero?
             # leading whitespace on a wrapped continuation: drop
           elsif line_w + w <= width
-            line_chars.concat(chars)
+            line_glyphs.concat(glyphs)
             line_w += w
           else
-            result << chars_to_styled(line_chars)
-            line_chars = []
+            result << glyphs_to_styled(line_glyphs)
+            line_glyphs = []
             line_w = 0
           end
         elsif line_w + w <= width
-          line_chars.concat(chars)
+          line_glyphs.concat(glyphs)
           line_w += w
         elsif w > width
-          result << chars_to_styled(line_chars) unless line_w.zero?
-          chunks = hard_break_chars(chars, width)
-          chunks[0..-2].each { |chunk| result << chars_to_styled(chunk) }
-          line_chars = chunks.last
-          line_w = line_chars.sum { |triple| triple[2] }
+          result << glyphs_to_styled(line_glyphs) unless line_w.zero?
+          chunks = hard_break_glyphs(glyphs, width)
+          chunks[0..-2].each { |chunk| result << glyphs_to_styled(chunk) }
+          line_glyphs = chunks.last
+          line_w = line_glyphs.sum { |triple| triple[2] }
         else
-          result << chars_to_styled(line_chars)
-          line_chars = chars
+          result << glyphs_to_styled(line_glyphs)
+          line_glyphs = glyphs
           line_w = w
         end
       end
-      result << chars_to_styled(line_chars)
+      result << glyphs_to_styled(line_glyphs)
       result
     end
 
+    # Splits into whitespace/word tokens by **grapheme cluster**, not character:
+    # a cluster is the unit a terminal draws, so measuring its parts separately
+    # would both mis-total an emoji sequence and let a wrap break a letter away
+    # from its combining mark.
     # @param hard_line [StyledString]
-    # @return [Array<Array>] tokens shaped `[type, chars, w]` where `type` is
-    #   `:space` or `:word`, `chars` is an `Array<[String, Style, Integer]>`
-    #   (char, style, display width), and `w` is the token's total width.
+    # @return [Array<Array>] tokens shaped `[type, glyphs, w]` where `type` is
+    #   `:space` or `:word`, `glyphs` is an `Array<[String, Style, Integer]>`
+    #   (grapheme cluster, style, display width), and `w` is the token's total
+    #   width.
     def tokenize_for_wrap(hard_line)
       tokens = []
-      current_chars = []
+      current_glyphs = []
       current_w = 0
       current_type = nil
 
-      hard_line.each_char_with_style do |c, s|
-        type = [" ", "\t"].include?(c) ? :space : :word
-        cw = Unicode::DisplayWidth.of(c)
+      each_glyph_with_style(hard_line) do |g, s|
+        type = [" ", "\t"].include?(g) ? :space : :word
+        gw = Buffer.display_width(g)
         if current_type && current_type != type
-          tokens << [current_type, current_chars, current_w]
-          current_chars = []
+          tokens << [current_type, current_glyphs, current_w]
+          current_glyphs = []
           current_w = 0
         end
         current_type = type
-        current_chars << [c, s, cw]
-        current_w += cw
+        current_glyphs << [g, s, gw]
+        current_w += gw
       end
-      tokens << [current_type, current_chars, current_w] unless current_chars.empty?
+      tokens << [current_type, current_glyphs, current_w] unless current_glyphs.empty?
       tokens
     end
 
-    # @param chars [Array<Array>] `[char, style, width]` triples.
+    # Like {#each_char_with_style} but per grapheme cluster. A cluster spanning a
+    # style boundary takes the style of its first span — pathological input, and
+    # splitting the cluster to honor both styles would paint a headless mark.
+    # @param styled [StyledString]
+    # @yieldparam glyph [String] one grapheme cluster.
+    # @yieldparam style [Style]
+    # @return [void]
+    def each_glyph_with_style(styled)
+      styled.spans.each do |span|
+        span.text.each_grapheme_cluster { |g| yield g, span.style }
+      end
+    end
+
+    # @param glyphs [Array<Array>] `[grapheme cluster, style, width]` triples.
     # @param width [Integer]
-    # @return [Array<Array<Array>>] each inner Array is a `chars`-shaped chunk.
-    def hard_break_chars(chars, width)
+    # @return [Array<Array<Array>>] each inner Array is a `glyphs`-shaped chunk.
+    def hard_break_glyphs(glyphs, width)
       chunks = []
       current = []
       current_w = 0
-      chars.each do |triple|
+      glyphs.each do |triple|
         cw = triple[2]
         if current_w + cw > width && current_w.positive?
           chunks << current
@@ -788,20 +814,20 @@ module Tuile
       chunks
     end
 
-    # @param chars [Array<Array>] `[char, style, width]` triples.
+    # @param glyphs [Array<Array>] `[grapheme cluster, style, width]` triples.
     # @return [StyledString]
-    def chars_to_styled(chars)
-      return self.class.new if chars.empty?
+    def glyphs_to_styled(glyphs)
+      return self.class.new if glyphs.empty?
 
       spans = []
       current_text = +""
-      current_style = chars.first[1]
-      chars.each do |c, s, _|
+      current_style = glyphs.first[1]
+      glyphs.each do |g, s, _|
         if s == current_style
-          current_text << c
+          current_text << g
         else
           spans << Span.new(text: current_text, style: current_style)
-          current_text = +c
+          current_text = +g
           current_style = s
         end
       end
@@ -809,6 +835,9 @@ module Tuile
       self.class.new(spans)
     end
 
+    # Walks **grapheme clusters**, so a slice boundary can never fall inside one:
+    # cutting a cluster would strand a combining mark with no base, which the
+    # painter drops outright, silently losing the accent off a letter.
     # @param text [String]
     # @param start_col [Integer]
     # @param len_col [Integer]
@@ -816,18 +845,18 @@ module Tuile
     def slice_text_by_columns(text, start_col, len_col)
       out = +""
       col = 0
-      text.each_char do |c|
-        cw = Unicode::DisplayWidth.of(c)
-        char_end = col + cw
-        if char_end <= start_col
+      text.each_grapheme_cluster do |g|
+        gw = Buffer.display_width(g)
+        glyph_end = col + gw
+        if glyph_end <= start_col
           # entirely before slice — skip
         elsif col >= start_col + len_col
           break
-        elsif col >= start_col && char_end <= start_col + len_col
-          out << c
+        elsif col >= start_col && glyph_end <= start_col + len_col
+          out << g
         end
-        # any other case = partial overlap with a wide char — drop
-        col = char_end
+        # any other case = partial overlap with a wide glyph — drop
+        col = glyph_end
       end
       out
     end

data/lib/tuile/theme.rb

@@ -1,67 +1,52 @@
 # frozen_string_literal: true
 
 module Tuile
-  # 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.
+  # 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 a {Screen#theme=}
+  # restyles everything via one invalidate-everything pass. Book ch6 is the
+  # concept in full (why accents-only, dark/light, live OS flips).
   #
-  # 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:
+  # The rendering helpers — {#active_bg}, {#active_border}, {#input_bg},
+  # {#hint} — 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}.
+  # Content passes through verbatim (so it may carry other escapes). For
+  # span-aware styling — a token applied to a {StyledString} without flattening
+  # its per-span colors — use the `*_color` readers instead
+  # (`with_bg(theme.active_bg_color)`). Rule of thumb: plain chrome → 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:
+  # Two built-in themes ship: {DARK} (default) and {LIGHT}. A custom one is one
+  # `with` away, and every token must be a {Color} instance — not the lenient
+  # {Color.coerce} forms, since a theme is declared once so the verbosity
+  # self-documents:
   #
   #   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:
+  # An app carries its own colors in {#custom} (frozen `Hash{Symbol => Color}`).
+  # Look them up with {#[]} (fail-fast on typos) and render with the generic
+  # {#fg} / {#bg} helpers; subclass for semantic readers (`Data#with` keeps the
+  # subclass). Pair dark/light variants in a {ThemeDef} for {Screen#theme_def=}.
   #
   #   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.
+  # For a color slot resolved *live* at paint — currently
+  # {Component#bg_color=} — assign a {Ref} instead of reading + rebuilding
+  # the token in {Component#on_theme_changed}; it tracks theme swaps on its
+  # own. Baked content colors ({Component::Label} text and friends) can't:
+  # they live in a frozen {StyledString} and still need the hook.
   #
   # @!attribute [r] active_bg_color
   #   Background highlight of the component the user is interacting with:
@@ -117,6 +102,58 @@ module Tuile
     #   loudly, not paint in a default.
     def [](token) = custom.fetch(token)
 
+    # The built-in chrome color tokens — every {Data} member bar {#custom}. A
+    # {Ref} resolves a name in this set as the chrome color; anything else as a
+    # {#custom} token.
+    # @return [Array<Symbol>]
+    CHROME_TOKENS = (members - %i[custom]).freeze
+
+    # @param name [Symbol] a token name.
+    # @return [Boolean] true iff `name` is a built-in chrome token (see
+    #   {CHROME_TOKENS}) rather than a {#custom} one.
+    def self.chrome_token?(name) = CHROME_TOKENS.include?(name)
+
+    # Builds a {Ref} — a live theme reference for a late-resolved color slot
+    # like {Component#bg_color=}. Sugar for `Theme::Ref.new(name)`.
+    # @param name [Symbol] a built-in chrome token ({#input_bg_color} etc.) or
+    #   a {#custom} token name.
+    # @return [Ref]
+    def self.ref(name) = Ref.new(name)
+
+    # A live reference to a theme token, resolved against the current theme at
+    # paint time rather than baked to a concrete {Color}. Assign one where a
+    # slot is resolved late — currently {Component#bg_color=} — and it follows
+    # light/dark flips with no {Component#on_theme_changed} hook:
+    #
+    #   panel.bg_color = Tuile::Theme.ref(:panel_bg)        # a #custom token
+    #   dropdown.bg_color = Tuile::Theme.ref(:input_bg_color) # built-in chrome
+    #
+    # The name may be a built-in chrome token ({CHROME_TOKENS}) or a {#custom}
+    # one; a chrome name takes precedence on the (pathological) collision. This
+    # does *not* add a global bg/fg token — it only lets a slot point at a
+    # color the theme *already* carries, resolved the same way framework chrome
+    # already resolves it.
+    #
+    # Distinct from {Color.coerce}'s symbol support, which names one of the 16
+    # ANSI colors and yields a fixed {Color}; a Ref names a *theme* token and
+    # re-reads it each paint.
+    #
+    # Immutable.
+    class Ref < Data.define(:name)
+      # Resolves to the concrete {Color} `name` maps to in `theme` — a built-in
+      # chrome reader when `name` is one ({Theme.chrome_token?}), else a
+      # {#custom} token.
+      # @param theme [Theme]
+      # @return [Color]
+      # @raise [KeyError] when `name` is neither a chrome token nor a {#custom}
+      #   token in `theme`.
+      def resolve(theme)
+        return theme.public_send(name) if Theme.chrome_token?(name)
+
+        theme[name]
+      end
+    end
+
     # Renders `text` in the foreground color of the app-specific `token`
     # — the generic counterpart of {#hint} for {#custom} tokens.
     # @param token [Symbol]