tuile 0.5.0 → 0.6.0

data/lib/tuile/component/text_field.rb

@@ -59,9 +59,8 @@ module Tuile
       def repaint
         return if rect.empty?
 
-        bg = active? ? ACTIVE_BG_SGR : INACTIVE_BG_SGR
         padded = @text + (" " * (rect.width - @text.length))
-        screen.print TTY::Cursor.move_to(rect.left, rect.top), bg, padded, Ansi::RESET
+        screen.print TTY::Cursor.move_to(rect.left, rect.top), background(padded)
       end
 
       protected

data/lib/tuile/component/text_input.rb

@@ -88,21 +88,6 @@ module Tuile
         invalidate
       end
 
-      # 256-color SGR for the focused-button highlight (matches what
-      # `Rainbow(...).bg(:darkslategray)` emits, which is what
-      # {Component::Button#repaint} uses for its focused state).
-      # @return [String]
-      ACTIVE_BG_SGR = "\e[48;5;59m"
-      # 256-color SGR for the unfocused field's "well": index 238 sits in
-      # the grayscale ramp (~#444444), bright enough to stand out against
-      # non-pure-black terminal themes (Gruvbox/Solarized/OneDark base
-      # backgrounds sit in the #1d–#2d range), and still distinctly darker
-      # than the active highlight at index 59 (~#5f5f5f). Rainbow's
-      # RGB-to-256 mapping snaps everything dark to palette index 16
-      # (terminal black), so we emit the escape directly to reach the ramp.
-      # @return [String]
-      INACTIVE_BG_SGR = "\e[48;5;238m"
-
       # Handles a key. Returns false when the component is inactive. Otherwise
       # first runs the {Component#handle_key} shortcut search via `super`, then
       # delegates to {#handle_text_input_key}.
@@ -117,6 +102,16 @@ module Tuile
 
       protected
 
+      # Renders `text` on the field's background well, looked up from the
+      # current {Screen#theme} at paint time: {Theme#active_bg} when this
+      # input is on the active (focus) chain, {Theme#input_bg} otherwise —
+      # visibly a field either way, distinctly highlighted when active.
+      # @param text [String]
+      # @return [String] ANSI-rendered text.
+      def background(text)
+        active? ? screen.theme.active_bg(text) : screen.theme.input_bg(text)
+      end
+
       # Input filter for {#text=}. Subclasses override to truncate or reject
       # invalid input. Default coerces to String.
       # @param new_text [String]

data/lib/tuile/component/text_view.rb

@@ -50,7 +50,6 @@ module Tuile
         @physical_lines = []
         @hard_line_wrap_counts = []
         @text = StyledString::EMPTY
-        @content_size = Size::ZERO
         @blank_line = StyledString::EMPTY
         @top_line = 0
         @auto_scroll = false
@@ -110,10 +109,10 @@ module Tuile
         @regions = [Region.send(:new, self, @hard_lines.size)]
         return if content_unchanged
 
-        @content_size = compute_content_size
         rewrap
         update_top_line_if_auto_scroll
         invalidate
+        self.content_size = compute_content_size
       end
 
       # Creates a new empty {Region} at the spatial tail of the document
@@ -180,9 +179,9 @@ module Tuile
 
         tail_region.send(:line_count=, tail_region.line_count + added)
         @text = nil
-        @content_size = compute_content_size
         update_top_line_if_auto_scroll
         invalidate
+        self.content_size = compute_content_size
       end
 
       # Verbatim append, returning `self` for chainability (`view << a << b`).
@@ -254,10 +253,10 @@ module Tuile
         end
 
         @text = nil
-        @content_size = compute_content_size
         @top_line = top_line_max if @top_line > top_line_max
         update_top_line_if_auto_scroll
         invalidate
+        self.content_size = compute_content_size
       end
 
       # Replaces a contiguous range of hard lines with the parsed content
@@ -315,10 +314,10 @@ module Tuile
         splice_hard_lines(from, length, new_hard_lines)
         update_region_counts(from, length, new_hard_lines.size)
         @text = nil
-        @content_size = compute_content_size
         @top_line = top_line_max if @top_line > top_line_max
         update_top_line_if_auto_scroll
         invalidate
+        self.content_size = compute_content_size
       end
 
       # Inserts `str` at hard-line index `at`. Equivalent to
@@ -529,10 +528,10 @@ module Tuile
         splice_hard_lines(start, old_count, new_lines)
         region.send(:line_count=, new_lines.size)
         @text = nil
-        @content_size = compute_content_size
         @top_line = top_line_max if @top_line > top_line_max
         update_top_line_if_auto_scroll
         invalidate
+        self.content_size = compute_content_size
       end
 
       # Region-scoped {#replace}. Validates `range` against
@@ -555,10 +554,10 @@ module Tuile
         splice_hard_lines(abs_from, length, new_hard_lines)
         region.send(:line_count=, region.line_count - length + new_hard_lines.size)
         @text = nil
-        @content_size = compute_content_size
         @top_line = top_line_max if @top_line > top_line_max
         update_top_line_if_auto_scroll
         invalidate
+        self.content_size = compute_content_size
       end
 
       # Verbatim append into `region`.
@@ -595,10 +594,10 @@ module Tuile
           region.send(:line_count=, region.line_count + rest.size)
         end
         @text = nil
-        @content_size = compute_content_size
         @top_line = top_line_max if @top_line > top_line_max
         update_top_line_if_auto_scroll
         invalidate
+        self.content_size = compute_content_size
       end
 
       # Drops the last `n` hard lines from `region`'s tail via
@@ -617,10 +616,10 @@ module Tuile
         splice_hard_lines(drop_from, to_drop, [])
         region.send(:line_count=, region.line_count - to_drop)
         @text = nil
-        @content_size = compute_content_size
         @top_line = top_line_max if @top_line > top_line_max
         update_top_line_if_auto_scroll
         invalidate
+        self.content_size = compute_content_size
       end
 
       # Drops `region` from {@regions}: its hard lines are removed via
@@ -643,10 +642,10 @@ module Tuile
         return unless had_lines
 
         @text = nil
-        @content_size = compute_content_size
         @top_line = top_line_max if @top_line > top_line_max
         update_top_line_if_auto_scroll
         invalidate
+        self.content_size = compute_content_size
       end
 
       # Adjusts region line counts after a {@hard_lines} splice that

data/lib/tuile/component/window.rb

@@ -19,9 +19,12 @@ module Tuile
         super()
         @border_right = 1
         @caption = caption
+        @content = nil
         # Optional bottom-row chrome that overlays the bottom border (e.g. a
         # search field).
         @footer = nil
+        @footer_sizing = Sizing::FILL
+        update_content_size
       end
 
       def focusable? = true
@@ -30,8 +33,25 @@ module Tuile
       #   row.
       attr_reader :footer
 
-      # Sets the bottom-row chrome slot. The footer overlays the bottom border at
-      # full inner width and is positioned automatically; pass `nil` to remove.
+      # @return [Sizing] how the footer's width is computed from the window's
+      #   inner width; defaults to {Sizing::FILL} (the footer spans the full
+      #   inner width). The footer's height is always 1 (the border row).
+      attr_reader :footer_sizing
+
+      # Sets the footer width policy and re-lays-out the footer.
+      # @param sizing [Sizing]
+      def footer_sizing=(sizing)
+        raise TypeError, "expected Sizing, got #{sizing.inspect}" unless sizing.is_a?(Sizing)
+        return if @footer_sizing == sizing
+
+        @footer_sizing = sizing
+        layout_footer
+        invalidate # repaint border cells the footer may have just vacated
+      end
+
+      # Sets the bottom-row chrome slot. The footer overlays the bottom border
+      # row and is positioned automatically — its width is governed by
+      # {#footer_sizing}; pass `nil` to remove.
       #
       # Symmetric to {#content=}: validates the new component, swaps parent
       # pointers, invalidates the old/new components and the window border, and
@@ -110,20 +130,36 @@ module Tuile
       def caption=(new_caption)
         @caption = new_caption
         invalidate
+        update_content_size
       end
 
-      # @return [Size] the size needed to fit the window's content, footer
-      #   (width only — footer overlays the bottom border), and caption,
-      #   plus the 2-character border. Returns {Size}`.new(2, 2)` when the
-      #   window has no content, footer, or caption.
-      def content_size
-        inner_w = [
-          content&.content_size&.width || 0,
-          @footer&.content_size&.width || 0,
-          frame_caption.length
-        ].max
-        inner_h = content&.content_size&.height || 0
-        Size.new(inner_w + 2, inner_h + 2)
+      # Sets the new content. Also recomputes the window's natural size.
+      # @param new_content [Component, nil]
+      def content=(new_content)
+        super
+        update_content_size
+      end
+
+      # Re-lays-out a {Sizing::WRAP_CONTENT} footer when the footer's natural
+      # size changes, and folds a content resize into the window's own
+      # natural size (whose change then bubbles to the window's parent — e.g.
+      # a {Popup} re-self-sizes). The footer deliberately does *not*
+      # participate in the window's {#content_size}: it is decoration
+      # overlaying the border, and must not drive the window's size — if it
+      # doesn't fit, it is clipped to the inner width.
+      # @param child [Component]
+      # @return [void]
+      def on_child_content_size_changed(child)
+        if child.equal?(@footer)
+          old_rect = @footer.rect
+          layout_footer
+          # Repaint on any footer geometry change: a shrinking footer vacates
+          # border cells that must be re-dashed (a growing one merely
+          # overdraws, but distinguishing isn't worth the code).
+          invalidate if @footer.rect != old_rect
+        else
+          update_content_size
+        end
       end
 
       # Fully repaints the window: both frame and contents.
@@ -150,6 +186,7 @@ module Tuile
         super
         # The shortcut key is shown in the caption — repaint.
         invalidate
+        update_content_size
       end
 
       protected
@@ -166,7 +203,7 @@ module Tuile
         return if rect.empty?
 
         frame = build_frame(frame_caption)
-        frame = Rainbow(frame).green if active?
+        frame = screen.theme.active_border(frame) if active?
         screen.print frame
       end
 
@@ -206,11 +243,28 @@ module Tuile
 
       private
 
+      # Recomputes the window's natural size: content's natural size (or the
+      # caption, whichever is wider) plus the 2-character border. The footer
+      # is deliberately excluded — see {#on_child_content_size_changed}. A
+      # window with no content or caption sizes to `Size.new(2, 2)` (bare
+      # border).
+      # @return [void]
+      def update_content_size
+        inner_w = [content&.content_size&.width || 0, frame_caption.length].max
+        inner_h = content&.content_size&.height || 0
+        self.content_size = Size.new(inner_w + 2, inner_h + 2)
+      end
+
+      # Positions the footer over the bottom border row, with its width
+      # resolved by {#footer_sizing} against the inner width. A
+      # {Sizing::WRAP_CONTENT} footer with zero natural width gets an empty
+      # rect — i.e. it is invisible, as if never assigned.
       # @return [void]
       def layout_footer
         return if @footer.nil? || rect.empty?
 
-        width = [rect.width - 2, 0].max
+        available = [rect.width - 2, 0].max
+        width = @footer_sizing.resolve(available, @footer.content_size.width)
         @footer.rect = Rect.new(rect.left + 1, rect.top + rect.height - 1, width, 1)
       end
     end

data/lib/tuile/component.rb

@@ -12,6 +12,8 @@ module Tuile
     def initialize
       @rect = Rect.new(0, 0, 0, 0)
       @active = false
+      @content_size = Size::ZERO
+      @on_theme_changed = nil
     end
 
     # @return [Rect] the rectangle the component occupies on screen.
@@ -195,6 +197,38 @@ module Tuile
     # @return [void]
     def on_focus; end
 
+    # Optional zero-arg listener fired by the base {#on_theme_changed} — the
+    # composition-style alternative to overriding the method, for apps that
+    # assemble stock components rather than subclass:
+    #
+    #   label.on_theme_changed = -> { label.text = render_status_line }
+    #
+    # @return [Proc, nil]
+    attr_writer :on_theme_changed
+
+    # Called on every attached component (pre-order, popups included) when
+    # {Screen#theme} changes — at {Screen#theme=} / {Screen#theme_def=}
+    # assignment and on OS appearance flips.
+    #
+    # Built-in components read {Screen#theme} at paint time, so their accents
+    # restyle automatically; this hook exists for *content* whose colors the
+    # app baked in from the old theme — a {Label#text} / {List#lines} /
+    # {TextView#text} {StyledString} styled with `theme[:accent]` and the
+    # like. Only the app knows which of its colors were theme-derived (as
+    # opposed to inherent to the data, e.g. log-level colors), so it rebuilds
+    # them here, re-running the same code that rendered them initially.
+    #
+    # Runs on the UI thread; {Screen#theme} already returns the new theme.
+    # Mutating content (`text=`, `lines=`, …) is safe — repaint coalesces per
+    # event-loop tick. Do not assign {Screen#theme=} from inside the hook.
+    #
+    # Subclasses overriding this should call `super` so an assigned
+    # {#on_theme_changed=} listener keeps firing.
+    # @return [void]
+    def on_theme_changed
+      @on_theme_changed&.call
+    end
+
     # @return [Boolean] true if this component's tree is currently mounted on
     #   the {Screen}, i.e. its root is the {ScreenPane}.
     def attached? = root == screen.pane
@@ -225,12 +259,27 @@ module Tuile
 
     # The {Size} big enough to show the entire component contents without
     # scrolling. Plain components have no intrinsic content and report
-    # {Size::ZERO}; container/decorative components (e.g. {Label}, {List},
-    # {Layout}, {Window}) override this to fold in their content's natural
-    # extent. Used by callers like {Component::Popup} to auto-size to
-    # whatever content was assigned, regardless of its concrete type.
+    # {Size::ZERO}; content-bearing components (e.g. {Label}, {List},
+    # {TextView}, {Window}) maintain it eagerly via {#content_size=} from
+    # their mutators, so reads are O(1). Used by callers like
+    # {Component::Popup} to auto-size to whatever content was assigned,
+    # regardless of its concrete type, and by {Sizing::WRAP_CONTENT} slots.
     # @return [Size]
-    def content_size = Size::ZERO
+    attr_reader :content_size
+
+    # Called by a child component whose {#content_size} just changed (fired
+    # from the child's {#content_size=}). Does nothing by default — a plain
+    # container is not size-coupled to its children. Containers that derive
+    # their own natural size or child layout from a child's natural size
+    # override this (e.g. {Component::Window} re-lays-out a
+    # {Sizing::WRAP_CONTENT} footer and recomputes its own size from content;
+    # {Component::Popup} re-self-sizes). If the receiver's own
+    # {#content_size} changes as a consequence, its {#content_size=} notifies
+    # *its* parent in turn — so the event bubbles exactly as far as geometry
+    # keeps changing, and stops where it doesn't.
+    # @param child [Component] the resized direct child.
+    # @return [void]
+    def on_child_content_size_changed(child); end
 
     # Where the hardware terminal cursor should sit when this component is the
     # cursor owner. Returns `nil` to indicate the cursor should be hidden. The
@@ -253,6 +302,26 @@ module Tuile
     # @return [void]
     def on_width_changed; end
 
+    # Memoizes the component's natural size and notifies {#parent} via
+    # {#on_child_content_size_changed} when the value actually changed.
+    # Subclasses call this from their content mutators (`text=`, `add_lines`,
+    # `caption=`, …) instead of caching ad-hoc.
+    #
+    # Call this as the *last* step of a mutator: the parent hook may
+    # reentrantly reposition this component (assign {#rect} — e.g. {Window}
+    # re-laying-out a wrap-content footer, or {Popup} re-self-sizing), which
+    # triggers {#on_width_changed} and {#repaint}-related recomputation, so
+    # all internal state must already be consistent.
+    # @param new_size [Size]
+    # @return [void]
+    def content_size=(new_size)
+      raise TypeError, "expected Size, got #{new_size.inspect}" unless new_size.is_a?(Size)
+      return if @content_size == new_size
+
+      @content_size = new_size
+      parent&.on_child_content_size_changed(self)
+    end
+
     # Invalidates the component: {Screen} records this component as
     # needs-repaint and once all events are processed, will call {#repaint}.
     #

data/lib/tuile/event_queue.rb

@@ -184,6 +184,31 @@ module Tuile
       def size = Size.new(width, height)
     end
 
+    # The terminal's color scheme changed — the user flipped the OS between
+    # light and dark appearance. Terminals supporting mode 2031 (kitty,
+    # foot, contour, ghostty, …) push the DSR-style report `\e[?997;1n`
+    # (dark) / `\e[?997;2n` (light) once {Screen#run_event_loop} enables
+    # the mode via {TerminalBackground::NOTIFY_ON}; the key thread parses
+    # it into this event and {Screen#event_loop} follows by assigning the
+    # matching {Theme}.
+    #
+    # @!attribute [r] scheme
+    #   @return [Symbol] `:light` or `:dark`.
+    class ColorSchemeEvent < Data.define(:scheme)
+      # The DSR-style color-scheme report: `\e[?997;1n` dark, `\e[?997;2n`
+      # light.
+      # @return [Regexp]
+      REPORT = /\A\e\[\?997;([12])n\z/
+
+      # @param key [String] key read via {Keys.getkey}.
+      # @return [ColorSchemeEvent, nil] nil when `key` is not a
+      #   color-scheme report.
+      def self.parse(key)
+        match = REPORT.match(key)
+        match && new(match[1] == "2" ? :light : :dark)
+      end
+    end
+
     # Emitted once when the queue is cleared, all messages are processed and the
     # event loop will block waiting for more messages. Perfect time for
     # repainting windows.
@@ -278,8 +303,7 @@ module Tuile
       @key_thread = Thread.new do
         loop do
           key = Keys.getkey
-          event = MouseEvent.parse(key)
-          event = KeyEvent.new(key) if event.nil?
+          event = MouseEvent.parse(key) || ColorSchemeEvent.parse(key) || KeyEvent.new(key)
           post event
         end
       rescue StandardError => e

data/lib/tuile/fake_screen.rb

@@ -54,5 +54,13 @@ module Tuile
     def invalidated_clear
       @invalidated.clear
     end
+
+    private
+
+    # No terminal probing in tests: skip {TerminalBackground.detect}
+    # (which would write an OSC 11 query to the test runner's TTY and
+    # steal its input) and pin the deterministic default.
+    # @return [Symbol]
+    def detect_scheme = :dark
   end
 end

data/lib/tuile/keys.rb

@@ -160,6 +160,16 @@ module Tuile
         char += $stdin.read(6 - char.bytesize)
       end
 
+      # Private-mode CSI reports (`\e[?` params… final byte in 0x40..0x7E)
+      # can outgrow the 5-byte gulp above — the mode-2031 color-scheme
+      # notification `\e[?997;1n` (see {EventQueue::ColorSchemeEvent}) is 8
+      # bytes after the `\e`. Drain to the final byte with blocking 1-byte
+      # reads so the tail doesn't surface as phantom keypresses. Keyboard
+      # sequences never start with `\e[?`, so this can't eat a regular key.
+      if char.start_with?("\e[?")
+        char += $stdin.read(1) until char.match?(/[\x40-\x7e]\z/)
+      end
+
       char
     end
   end

data/lib/tuile/screen.rb

@@ -35,6 +35,9 @@ module Tuile
       @repainting = Set.new
       # Until the event loop is run, we pretend we're in the UI thread.
       @pretend_ui_lock = true
+      @scheme = detect_scheme
+      @theme_def = ThemeDef.default
+      @theme = @theme_def.for(@scheme)
       # Structural root of the component tree: holds tiled content, popup
       # stack and status bar.
       @pane = ScreenPane.new
@@ -93,6 +96,66 @@ module Tuile
     # @return [Size] current screen size.
     attr_reader :size
 
+    # The color {Theme} built-in components read at paint time: the member
+    # of {#theme_def} matching the terminal background detected at
+    # construction (see {TerminalBackground.detect}; inconclusive means
+    # dark). While the event loop runs, terminals supporting mode 2031
+    # push OS appearance changes ({EventQueue::ColorSchemeEvent}) and the
+    # screen re-picks from {#theme_def}.
+    # @return [Theme]
+    attr_reader :theme
+
+    # The app's {ThemeDef} — the dark/light {Theme} pair the screen picks
+    # {#theme} from, at startup and on every OS appearance flip. Starts as
+    # {ThemeDef.default} ({ThemeDef::DEFAULT} unless reassigned — tests
+    # do, see {ThemeDef.default=}). Assigning a custom definition is the
+    # durable way to theme an app: unlike a bare {#theme=}, it survives
+    # the user toggling the OS appearance.
+    # @return [ThemeDef]
+    attr_reader :theme_def
+
+    # Replaces the theme definition and immediately applies the member
+    # matching the current color scheme (via {#theme=}, so the whole UI
+    # restyles — or nothing repaints if that member equals the current
+    # theme).
+    # @param theme_def [ThemeDef]
+    # @return [void]
+    def theme_def=(theme_def)
+      raise TypeError, "expected ThemeDef, got #{theme_def.inspect}" unless theme_def.is_a?(ThemeDef)
+
+      check_locked
+      @theme_def = theme_def
+      self.theme = @theme_def.for(@scheme)
+    end
+
+    # Replaces the theme and restyles the whole UI: fires
+    # {Component#on_theme_changed} across the attached tree (so the app can
+    # rebuild styled content whose colors were derived from the old theme),
+    # refreshes the status bar and invalidates every attached component so
+    # the next repaint uses the new colors. No-op when `new_theme` equals
+    # the current theme.
+    #
+    # This is a transient override: the next OS appearance flip re-picks
+    # from {#theme_def} and replaces it. To theme an app durably, assign
+    # {#theme_def=} instead.
+    #
+    # Note status-bar hints supplied by the host as preformatted strings
+    # (see {#register_global_shortcut}) have their colors baked in and are
+    # not restyled by this.
+    # @param new_theme [Theme]
+    # @return [void]
+    def theme=(new_theme)
+      raise TypeError, "expected Theme, got #{new_theme.inspect}" unless new_theme.is_a?(Theme)
+
+      check_locked
+      return if @theme == new_theme
+
+      @theme = new_theme
+      @pane&.on_tree(&:on_theme_changed)
+      refresh_status_bar
+      needs_full_repaint
+    end
+
     # @return [Array<Component>] currently active popup components (forwarded
     #   to {ScreenPane}). The array must not be modified!
     def popups = @pane.popups
@@ -172,7 +235,7 @@ module Tuile
       top_popup = @pane.popups.last
       globals = global_shortcut_hints(popup_open: !top_popup.nil?)
       @pane.status_bar.text = if top_popup.nil?
-                                ["q #{Rainbow("quit").cadetblue}", *globals,
+                                ["q #{@theme.hint("quit")}", *globals,
                                  active_window&.keyboard_hint].compact.reject(&:empty?).join("  ")
                               else
                                 [*globals, top_popup.keyboard_hint].reject(&:empty?).join("  ")
@@ -224,10 +287,15 @@ module Tuile
       @pretend_ui_lock = false
       $stdin.echo = false
       print MouseEvent.start_tracking if capture_mouse
+      # Follow OS light/dark flips live: terminals supporting mode 2031
+      # push color-scheme reports that the key thread turns into
+      # {EventQueue::ColorSchemeEvent}s.
+      print TerminalBackground::NOTIFY_ON
       $stdin.raw do
         event_loop
       end
     ensure
+      print TerminalBackground::NOTIFY_OFF
       print MouseEvent.stop_tracking if capture_mouse
       print TTY::Cursor.show
       $stdin.echo = true
@@ -272,7 +340,7 @@ module Tuile
     #
     #   screen.register_global_shortcut(Keys::CTRL_L,
     #                                   over_popups: true,
-    #                                   hint: "^L #{Rainbow("log").cadetblue}") do
+    #                                   hint: "^L #{screen.theme.hint("log")}") do
     #     log_popup.open
     #   end
     #
@@ -283,8 +351,9 @@ module Tuile
     #   (default), the shortcut is suppressed while any popup is open and
     #   the popup gets the key instead.
     # @param hint [String, nil] preformatted status-bar hint (e.g.
-    #   `"^L #{Rainbow("log").cadetblue}"`). When nil (default) the shortcut
-    #   is silent in the status bar.
+    #   `"^L #{screen.theme.hint("log")}"`). When nil (default) the shortcut
+    #   is silent in the status bar. The colors are baked into the string,
+    #   so a later {#theme=} does not restyle it — re-register if needed.
     # @yield invoked with no arguments when `key` is pressed.
     # @return [void]
     def register_global_shortcut(key, over_popups: false, hint: nil, &block)
@@ -476,6 +545,27 @@ module Tuile
 
     private
 
+    # Startup color scheme: `:light` when {TerminalBackground.detect}
+    # reports a light terminal background, `:dark` otherwise (including
+    # when detection is inconclusive). Runs in the constructor — the
+    # OSC 11 reply arrives on stdin, which is only safe to read before
+    # {EventQueue#start_key_thread} owns it. {FakeScreen} overrides this
+    # to pin `:dark`, keeping specs deterministic and off the test
+    # runner's TTY.
+    # @return [Symbol] `:dark` or `:light`.
+    def detect_scheme
+      TerminalBackground.detect == :light ? :light : :dark
+    end
+
+    # An OS appearance flip arrived (mode-2031 report): remember the
+    # scheme and apply the matching member of {#theme_def}.
+    # @param scheme [Symbol] `:dark` or `:light`.
+    # @return [void]
+    def on_color_scheme(scheme)
+      @scheme = scheme
+      self.theme = @theme_def.for(@scheme)
+    end
+
     # Walks the current modal scope in pre-order, collects tab stops, and
     # advances focus by one (wrapping). When the focused component isn't in
     # the tab order (e.g. focus is parked on a popup/window chrome with no
@@ -596,6 +686,8 @@ module Tuile
         when EventQueue::TTYSizeEvent
           @size = event.size
           layout
+        when EventQueue::ColorSchemeEvent
+          on_color_scheme(event.scheme)
         when EventQueue::EmptyQueueEvent
           repaint
         when Proc