tuile 0.13.0 → 0.14.0

data/lib/tuile/component.rb

@@ -9,7 +9,43 @@ module Tuile
   # any stale invalidation entries are filtered out at drain time. Subclasses
   # can paint freely in {#repaint} without re-asserting attachment.
   class Component
+    # The methods that *define* the tree, and so may never be overridden —
+    # {#attached?} walks the parent chain while every subtree walk uses
+    # {#children}, and an override that makes those two disagree leaves a
+    # component attached but never painted, with nothing raising (`D_final_tree`).
+    # Enforced by {.verify_final!}; reparent through {#add_child} /
+    # {#remove_child} / {#detach_child}, and hold a {Slot} for a swappable region.
+    # @return [Array<Symbol>]
+    FINAL_METHODS = %i[children parent parent= add_child remove_child detach_child].freeze
+
+    @final_verified = {}
+
+    # Raises unless `klass` inherits every {FINAL_METHODS} entry from
+    # {Component}; memoized, so it costs one hash lookup per construction.
+    #
+    # Comparing each *resolved* method's `owner` is what makes this catch all
+    # four routes in — `def`, `define_method`, an included module, a `prepend`.
+    # A `method_added` hook would fire earlier but see only the first two.
+    # @param klass [Class] the class being instantiated.
+    # @raise [Error] if any final method has been overridden.
+    # @return [void]
+    def self.verify_final!(klass)
+      return if @final_verified.key?(klass)
+
+      overridden = FINAL_METHODS.reject { klass.instance_method(_1).owner == Component }
+      unless overridden.empty?
+        raise Error, "#{klass} overrides #{overridden.join(", ")}, which are final on Component. " \
+                     "The tree is the framework's single source of truth — #attached? walks the " \
+                     "parent chain while subtree walks use #children, so an override desyncs them " \
+                     "silently. Reparent through add_child / remove_child / detach_child; for a " \
+                     "swappable region, hold a Component::Slot."
+      end
+
+      @final_verified[klass] = true
+    end
+
     def initialize
+      Component.verify_final!(self.class)
       @rect = Rect.new(0, 0, 0, 0)
       @active = false
       @on_theme_changed = nil
@@ -20,6 +56,65 @@ module Tuile
     # @return [Rect] the rectangle the component occupies on screen.
     attr_reader :rect
 
+    # The three readers below report the geometry a parent *assigned*, as
+    # shorthand for the matching {#rect} field. They are reports, not requests:
+    # no container consults them when dividing space, and there is deliberately
+    # no writer — layout is top-down (`DECISIONS.md` `D_box_layouts`), so a
+    # component says how big it *is*, never how big it wants to be.
+
+    # @return [Size] `rect.size`.
+    def size = rect.size
+
+    # @return [Integer] `rect.width`.
+    def width = rect.width
+
+    # @return [Integer] `rect.height`.
+    def height = rect.height
+
+    # The size of the region this component paints, or `nil` (the default) to
+    # declare nothing — in which case the whole {#rect} is treated as fair game
+    # and the default {#repaint} blanks all of it. Override it when you paint
+    # less: a one-row {Component::Checkbox} handed a tall column, or a
+    # {Component::Select} used as a {Component::Popup}'s content and assigned the
+    # whole inner box.
+    #
+    # It always sits at {#rect}'s top-left — which is why this is a {Size} and
+    # not a {Rect}: an offset extent is not merely unsupported, it is
+    # unrepresentable. Use {#extent_rect} where coordinates are wanted.
+    #
+    # **`nil` is not the same as `rect.size`.** `nil` says "I have not declared
+    # what I paint, so clear everything before I do", which is what a
+    # {Component::Label} with short text needs. A declared extent — even one that
+    # happens to equal the rect, as a one-row {Component::Select} in a one-row
+    # rect does — says "I paint this in full, don't blank it", which is what
+    # keeps the default {#repaint} from dirtying cells it is about to redraw
+    # (`D_progress_bar`). The base cannot tell those apart from the value alone;
+    # that is what the `nil` carries.
+    #
+    # It flows **downward only**: no container consults it when dividing space,
+    # so {#rect} still means exactly what the parent assigned (`D_extent`). Three
+    # things read it, all of them this component or the framework painting it:
+    # {#clear_outside_extent} blanks the dead tail, {#handle_mouse} hit-tests
+    # against it so a click on that tail doesn't activate the widget, and a
+    # dropdown anchors under it rather than under unused space.
+    #
+    # **An override promises to paint the extent in full**, so `super` in
+    # {#repaint} blanks only what is outside it. The arithmetic is each widget's
+    # own — caption width, painted strip, one row — and must not vary with
+    # {#bg_color} (`D_boolean_fields`).
+    # @return [Size, nil]
+    def extent = nil
+
+    # {#extent} placed at {#rect}'s top-left, for the consumers that need
+    # coordinates: `extent_rect.contains?(event.point)` in a {#handle_mouse}, and
+    # the anchor a dropdown hangs from. Total — an undeclared {#extent} yields
+    # the whole {#rect}, so a generic caller never sees `nil`.
+    # @return [Rect]
+    def extent_rect
+      e = extent
+      e.nil? ? rect : Rect.new(rect.left, rect.top, e.width, e.height)
+    end
+
     # Sets new position of the component. This is the absolute component
     # positioning on screen, not a relative positioning relative to component's
     # {#parent}.
@@ -104,6 +199,11 @@ module Tuile
     # paint the whole {#rect} yourself ({Window}'s border, {Component::List}'s
     # row-by-row paint). Never draw outside {#rect}. Only called when attached.
     #
+    # **A widget that paints less than its rect declares an {#extent} rather than
+    # skipping `super`.** The clear then covers only what is outside it, so the
+    # cells it is about to repaint are not blanked first — blanking them would
+    # mark them dirty and make {Buffer#flush} re-emit them (`D_progress_bar`).
+    #
     # **The children are re-invalidated whether or not they tile.** A container
     # that paints nothing of its own can only redraw its area *through* them, so
     # a tiling container that skipped this would be a dead end in the cascade: an
@@ -116,7 +216,7 @@ module Tuile
     def repaint
       return if rect.empty?
 
-      clear_background unless children.any? && children_tile_rect?
+      clear_outside_extent unless children.any? && children_tile_rect?
       children.each { |c| screen.invalidate(c) }
     end
 
@@ -152,12 +252,21 @@ module Tuile
       false
     end
 
-    # Handles mouse event. Default implementation focuses this component when
-    # clicked (if {#focusable?}).
+    # Focuses this component when left-clicked (if {#focusable?}), then hands the
+    # event down to every child whose {#rect} contains the point — which is how a
+    # click descends the tiled tree to a leaf.
+    #
+    # A widget that resolves clicks *inside* its own rect — mapping a point to a
+    # row, or toggling an overlay — overrides this and does not call `super`.
+    # Such an override hit-tests {#extent_rect} rather than {#rect}, so a click
+    # on the tail it doesn't paint never activates it.
     # @param event [MouseEvent]
     # @return [void]
     def handle_mouse(event)
       screen.focused = self unless event.button != :left || active? || !focusable?
+      # Snapshot: a handler may add or remove siblings (a click that swaps a
+      # slot's occupant), and `each` over a mutating array skips an entry.
+      children.dup.each { |c| c.handle_mouse(event) if c.rect.contains?(event.point) }
     end
 
     # @return [Boolean] true if the component is on the active chain — i.e. it
@@ -238,22 +347,6 @@ module Tuile
     # @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=} and on
-    # OS appearance flips. The hook exists for app *content* whose colors were
-    # baked in from the old theme (a {Label#text} / {List#lines=} {StyledString}
-    # styled with `theme[:accent]`); rebuild it here by re-running the code that
-    # rendered it. See book ch6 for why built-in accents need no such handling.
-    #
-    # Runs on the UI thread with {Screen#theme} already updated, so mutating
-    # content (`text=`, `lines=`, …) is safe. Do not assign {Screen#theme=}
-    # here. Subclasses overriding this must call `super` so an assigned
-    # {#on_theme_changed=} listener keeps firing.
-    # @return [void]
-    def on_theme_changed
-      @on_theme_changed&.call
-    end
-
     # Whether this component's tree is mounted on a UI, {ScreenPane} being the
     # root of every displayed tree.
     #
@@ -427,6 +520,26 @@ module Tuile
     # @return [void]
     def on_width_changed; end
 
+    # Called on every attached component (pre-order, popups included) when
+    # {Screen#theme} changes — at {Screen#theme=} / {Screen#theme_def=} and on
+    # OS appearance flips. The hook exists for app *content* whose colors were
+    # baked in from the old theme (a {Label#text} / {List#lines=} {StyledString}
+    # styled with `theme[:accent]`); rebuild it here by re-running the code that
+    # rendered it. See book ch6 for why built-in accents need no such handling.
+    #
+    # Runs on the UI thread with {Screen#theme} already updated, so mutating
+    # content (`text=`, `lines=`, …) is safe. Do not assign {Screen#theme=}
+    # here. Subclasses overriding this must call `super` so an assigned
+    # {#on_theme_changed=} listener keeps firing.
+    #
+    # Plumbing an app overrides and never calls, hence protected — and
+    # {Screen}, not being a {Component}, fans it out through `__send__`, so an
+    # override is free to declare any visibility (`D_hook_visibility`).
+    # @return [void]
+    def on_theme_changed
+      @on_theme_changed&.call
+    end
+
     # Invalidates the component: {Screen} records this component as
     # needs-repaint and once all events are processed, will call {#repaint}.
     #
@@ -455,6 +568,23 @@ module Tuile
       total >= rect.width * rect.height
     end
 
+    # Blanks the part of {#rect} outside {#extent} — the dead tail a widget that
+    # paints less than it was given must not leave stale. Up to two regions,
+    # since a narrowed extent leaves an L: the columns right of it, and the rows
+    # below it. A `nil` extent declares nothing, so the whole rect is blanked.
+    # Called by the default {#repaint}; a self-painter that skips `super` calls
+    # it directly.
+    # @return [void]
+    def clear_outside_extent
+      e = extent
+      return clear_background if e.nil? # nothing declared: all of it is fair game
+
+      right = Rect.new(rect.left + e.width, rect.top, rect.width - e.width, e.height)
+      below = Rect.new(rect.left, rect.top + e.height, rect.width, rect.height - e.height)
+      clear_background(right) unless right.empty?
+      clear_background(below) unless below.empty?
+    end
+
     # Clears the background: fills every cell with a blank in the
     # {#effective_bg_color} (the terminal default when none is inherited).
     #

data/lib/tuile/event_queue.rb

@@ -247,6 +247,25 @@ module Tuile
       end
     end
 
+    # The terminal reported its background color — an OSC 11 reply, read
+    # back as a whole "key" by {Keys.getkey}.
+    #
+    # Only ever an answer to a {TerminalBackground::QUERY} someone wrote,
+    # and only the color: a {ColorSchemeEvent} is what prompts the re-probe
+    # and what carries the light/dark half. See {Screen#background_color}.
+    #
+    # @!attribute [r] color
+    #   @return [Color] the reported background, 24-bit RGB.
+    class BackgroundColorEvent < Data.define(:color)
+      # @param key [String] key read via {Keys.getkey}.
+      # @return [BackgroundColorEvent, nil] nil when `key` is not an OSC 11
+      #   background reply.
+      def self.parse(key)
+        result = TerminalBackground.parse(key)
+        result&.color && new(result.color)
+      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.
@@ -344,7 +363,8 @@ module Tuile
           event = if key == Keys::PASTE_START
                     PasteEvent.new(Keys.read_paste)
                   else
-                    MouseEvent.parse(key) || ColorSchemeEvent.parse(key) || KeyEvent.new(key)
+                    MouseEvent.parse(key) || ColorSchemeEvent.parse(key) ||
+                      BackgroundColorEvent.parse(key) || KeyEvent.new(key)
                   end
           post event
         end

data/lib/tuile/fake_screen.rb

@@ -81,12 +81,36 @@ module Tuile
       @invalidated.clear
     end
 
+    # Plays the terminal answering the OSC 11 re-probe, so a spec can
+    # exercise app code that derives colors from {#background_color}:
+    #
+    #   Screen.instance.background_color = Color.rgb(30, 30, 46)
+    #
+    # Takes the same path a real reply does — a changed color fires
+    # {Component#on_theme_changed} across the tree and invalidates it.
+    # There is no such writer on {Screen}: the value is a report from the
+    # terminal, not a setting.
+    # @param color [Color]
+    # @return [void]
+    def background_color=(color)
+      on_background_color(color)
+    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.
+    # steal its input) and pin the deterministic default. The color is nil
+    # — the case every app must handle anyway — until a spec assigns one
+    # through {#background_color=}.
+    # @return [TerminalBackground::Result]
+    def detect_background = TerminalBackground::Result.new(scheme: :dark, color: nil)
+
+    # Pins the depth rather than reading the test runner's environment, so a
+    # spec asserting flushed bytes gets the same answer on a truecolor
+    # terminal, under `TERM=dumb` in CI, and inside tmux. A spec exercising
+    # degradation builds its own {Buffer} with the depth it wants.
     # @return [Symbol]
-    def detect_scheme = :dark
+    def detect_color_depth = :truecolor
   end
 end

data/lib/tuile/keys.rb

@@ -184,6 +184,13 @@ module Tuile
       # sequences never start with `\e[?`, so this can't eat a regular key.
       char += $stdin.read(1) while char.start_with?("\e[?") && !char.match?(/[\x40-\x7e]\z/)
 
+      # OSC replies (the ~22-byte background report, {TerminalBackground})
+      # outgrow the gulp too, and end in BEL or ST rather than at a fixed
+      # length. Byte-at-a-time is required, not merely tidy: ST *is* `\e\\`,
+      # so a gulping read would swallow it plus the keys typed behind it.
+      # Keyboard sequences never start with `\e]`, so this eats no real key.
+      char += $stdin.read(1) while char.start_with?("\e]") && !char.end_with?("\a", "\e\\")
+
       char
     end
 

data/lib/tuile/screen.rb

@@ -16,13 +16,13 @@ module Tuile
   # out its own children), the modal/overlay {#popups} stack (opened via
   # {Component::Popup#open}, drawn on top of the content). Popups are *not*
   # sized from their content — each carries its own top-down
-  # {Component::Popup#size} — and they deliberately overdraw the content
+  # {Component::Popup#declared_size} — and they deliberately overdraw the content
   # without clipping.
   #
   # Tuile draws no chrome of its own: there is no status bar and no reserved
   # row, so {#content} gets the whole terminal. An app that wants a status line
   # builds one into its own layout and drives it from {#on_focus_changed=}
-  # (`D-status-bar`).
+  # (`D_status_bar`).
   #
   # ## Repaint model
   #
@@ -71,7 +71,10 @@ module Tuile
       # during :idle, at both ends of the screen's life. See {#check_locked}.
       @ui_thread = Thread.current
       @closed = false
-      @color_scheme = detect_scheme
+      background = detect_background
+      @color_scheme = background.scheme
+      @background_color = background.color
+      @color_depth = detect_color_depth
       @theme_def = ThemeDef.default
       @theme = @theme_def.for(@color_scheme)
       # Structural root of the component tree: holds tiled content and the
@@ -84,7 +87,7 @@ module Tuile
       # The back buffer components paint into. {#repaint} flushes its diff to
       # the terminal, so only changed cells are emitted (flicker-free on any
       # terminal). Sized to the current viewport; {#layout} resizes it.
-      @buffer = Buffer.new(@size)
+      @buffer = Buffer.new(@size, color_depth: @color_depth)
     end
 
     # Entry in the global shortcut registry: the block to run, and whether it
@@ -118,6 +121,17 @@ module Tuile
     # @return [Symbol] `:light` or `:dark`
     attr_reader :color_scheme
 
+    # How many colors this terminal can show ({ColorDepth::DEPTHS}), detected
+    # at construction. {Buffer#flush} degrades every color it emits to this,
+    # so an app may compute an RGB tint — say from {#background_color} — and
+    # paint with it, whatever the terminal turns out to understand.
+    #
+    # Deliberately read-only: detection runs once and the answer can't change
+    # mid-session. Override a terminal that reports itself wrong through
+    # {ColorDepth::OVERRIDE_ENV} instead.
+    # @return [Symbol]
+    attr_reader :color_depth
+
     # @return [Buffer] the back buffer components paint into
     #   ({Buffer#set_text} / {Buffer#fill} / {Buffer#set_char}).
     attr_reader :buffer
@@ -183,6 +197,26 @@ module Tuile
     # @return [ThemeDef]
     attr_reader :theme_def
 
+    # The terminal's own background, as it reported it — for deriving a
+    # color *from* the background rather than picking one against it. A pane
+    # tinted a few percent off it sits right on any terminal, where a fixed
+    # near-neutral only sits right near the one it was tuned on:
+    #
+    #   bg = screen.background_color
+    #   sidebar.bg_color =
+    #     bg ? Color.rgb(*bg.value.map { (_1 + 10).clamp(0, 255) }) : FALLBACK_TINT
+    #
+    # **Nil is the normal case, not an edge** — a terminal answering only
+    # `COLORFGBG`, or neither probe, reports no RGB at all. Keep a fallback.
+    #
+    # Kept current across OS appearance flips, a frame behind: the flip
+    # report carries light/dark only, so the screen re-probes and this
+    # updates when the reply lands. A changed color then fires
+    # {Component#on_theme_changed} across the tree exactly as a theme swap
+    # does — a background-derived tint *is* a theme-derived color.
+    # @return [Color, nil]
+    attr_reader :background_color
+
     # 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
@@ -211,12 +245,15 @@ module Tuile
       return if @theme == new_theme
 
       @theme = new_theme
-      @pane&.on_tree(&:on_theme_changed)
+      # `__send__`, not `&:on_theme_changed`: the hook is protected, and an app
+      # subclass may narrow it further (`D_hook_visibility`).
+      @pane&.on_tree { _1.__send__(:on_theme_changed) }
       needs_full_repaint
     end
 
-    # @return [Array<Component>] currently active popup components (forwarded
-    #   to {ScreenPane}). The array must not be modified!
+    # @return [Array<Component::Overlay>] the open overlay stack — both
+    #   {Component::Popup} modals and bare {Component::Overlay}s — in stacking
+    #   order (forwarded to {ScreenPane}). The array must not be modified!
     def popups = @pane.popups
 
     # @return [EventQueue] the event queue.
@@ -316,7 +353,7 @@ module Tuile
     #
     # This is the hook an app drives its own status line from. Tuile owns no
     # status bar and reserves no row: build a {Component::Label} into your own
-    # layout and fill it here (`D-status-bar`).
+    # layout and fill it here (`D_status_bar`).
     #
     #   screen.on_focus_changed = -> { bar.text = hint_for(screen.focused) }
     #
@@ -335,10 +372,10 @@ module Tuile
     # @return [Proc, nil]
     attr_accessor :on_focus_changed
 
-    # Internal — use {Component::Popup#open} instead. Adds the popup to
-    # {#pane}, centers and focuses it.
+    # Internal — use {Component::Overlay#open} instead. Adds the overlay to
+    # {#pane}; a {Component::Popup} is additionally centered and focused.
     # @api private
-    # @param window [Component::Popup]
+    # @param window [Component::Overlay] any overlay, modal or not.
     # @return [void]
     def add_popup(window)
       check_locked
@@ -469,12 +506,12 @@ module Tuile
       @global_shortcuts.delete(key)
     end
 
-    # Internal — use {Component::Popup#close} instead. Removes the popup
+    # Internal — use {Component::Overlay#close} instead. Removes the overlay
     # from {#pane}, repairs focus, and repaints the scene.
     #
-    # Does nothing if the window is not open on this screen.
+    # Does nothing if the overlay is not open on this screen.
     # @api private
-    # @param window [Component::Popup]
+    # @param window [Component::Overlay] any overlay, modal or not.
     # @return [void]
     def remove_popup(window)
       check_locked
@@ -497,10 +534,10 @@ module Tuile
       @pane&.on_tree { invalidate _1 }
     end
 
-    # Internal — use {Component::Popup#open?} instead.
+    # Internal — use {Component::Overlay#open?} instead.
     # @api private
-    # @param window [Component::Popup]
-    # @return [Boolean] true if this popup is currently mounted.
+    # @param window [Component::Overlay] any overlay, modal or not.
+    # @return [Boolean] true if this overlay is currently mounted.
     def has_popup?(window) # rubocop:disable Naming/PredicatePrefix
       check_locked
       @pane.has_popup?(window)
@@ -546,15 +583,20 @@ module Tuile
     end
 
     # Writes terminal-housekeeping escapes straight to stdout: {#clear},
-    # mouse-tracking start/stop, the color-scheme notify toggles, cursor-show
-    # on teardown. Component painting does *not* go through here anymore — it
-    # writes into {#buffer}, which {#repaint} diffs and {#emit}s. {FakeScreen}
-    # overrides this (and {#emit}) to capture into `@prints` instead of the
-    # test runner's stdout.
+    # mouse-tracking start/stop, the color-scheme notify toggles, the OSC 11
+    # background re-probe, cursor-show on teardown. Component painting does
+    # *not* go through here anymore — it writes into {#buffer}, which
+    # {#repaint} diffs and {#emit}s. {FakeScreen} overrides this (and
+    # {#emit}) to capture into `@prints` instead of the test runner's stdout.
+    #
+    # Flushed, like {#emit}: none of these escapes ends in a newline, and a
+    # buffered stdout would hold a *query* — one whose reply the app is
+    # waiting on — until the next frame went out.
     # @param args [String] stuff to print.
     # @return [void]
     def print(*args)
       Kernel.print(*args)
+      $stdout.flush
     end
 
     # Rings the terminal bell ({Ansi::BEL}) — the signal for a keystroke that
@@ -624,12 +666,22 @@ module Tuile
           tiled_invalidated = true
         end
 
-        # Popups on top: the whole stack when a tiled repaint may have clobbered
-        # cells they share in the buffer, else just the invalidated popup
-        # components. Overdraw into the buffer is free (only net-visible cell
-        # changes reach the terminal), so reasserting the stack is cheap.
+        # Popups on top: a layer repaints whole whenever anything *beneath* it —
+        # the tiled tree, or a lower popup — repaints, else just its invalidated
+        # members. Layer-by-layer rather than one tiled_invalidated bool because
+        # the drain loops: a lower popup's repaint cascade re-invalidates
+        # children into the *next* iteration (its gap-clearing Layout wipes and
+        # re-queues a button, say), and that iteration has no tiled repaint —
+        # only the full re-assert of every layer above keeps the stacking order
+        # true across iterations (screen_spec pins it with two overlapping
+        # popups). Overdraw into the buffer is free (only net-visible cell
+        # changes reach the terminal), so reasserting layers is cheap.
+        below_repainted = tiled_invalidated
         popups.each do |p|
-          p.on_tree { |c| repaint << c if tiled_invalidated || @invalidated.include?(c) }
+          layer_invalidated = false
+          p.on_tree { |c| layer_invalidated ||= @invalidated.include?(c) }
+          p.on_tree { |c| repaint << c if below_repainted || @invalidated.include?(c) }
+          below_repainted ||= layer_invalidated
         end
 
         @repainting = repaint.to_set
@@ -654,25 +706,53 @@ 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
+    # The startup background probe, seeding {#theme} and
+    # {#background_color}. Inconclusive detection means `:dark` with no
+    # color. 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 the result, keeping specs
+    # deterministic and off the test runner's TTY.
+    # @return [TerminalBackground::Result]
+    def detect_background
+      TerminalBackground.detect || TerminalBackground::Result.new(scheme: :dark, color: nil)
     end
 
+    # The startup color-depth probe, seeding {#color_depth}. Reads the
+    # environment only, so unlike {#detect_background} it has no timing
+    # constraint. {FakeScreen} overrides it to pin the result, keeping specs
+    # off whatever `COLORTERM` the test runner happens to carry.
+    # @return [Symbol]
+    def detect_color_depth = ColorDepth.detect
+
     # An OS appearance flip arrived (mode-2031 report): remember the
-    # scheme and apply the matching member of {#theme_def}.
+    # scheme, apply the matching member of {#theme_def}, and re-probe for
+    # the new background RGB, which the report does not carry.
+    #
+    # The query goes out from *this* thread — the event-loop thread, which
+    # also owns {#emit} — so its bytes can never land inside a frame's
+    # synchronized-output batch. The reply comes back through the key
+    # thread as an {EventQueue::BackgroundColorEvent}.
     # @param scheme [Symbol] `:dark` or `:light`.
     # @return [void]
     def on_color_scheme(scheme)
       @color_scheme = scheme
       self.theme = @theme_def.for(@color_scheme)
+      print TerminalBackground::QUERY
+    end
+
+    # The re-probe answered: adopt the color and restyle, since an app's
+    # background-derived tints are now a scheme behind. Deliberately keeps
+    # the previous color until the reply lands rather than blanking it on
+    # the flip — a terminal that reports mode-2031 flips but not OSC 11
+    # would otherwise lose the color it gave us at startup, permanently.
+    # @param color [Color]
+    # @return [void]
+    def on_background_color(color)
+      return if @background_color == color
+
+      @background_color = color
+      @pane&.on_tree { _1.__send__(:on_theme_changed) }
+      needs_full_repaint
     end
 
     # Walks the current modal scope in pre-order, collects tab stops, and
@@ -802,6 +882,8 @@ module Tuile
           layout
         when EventQueue::ColorSchemeEvent
           on_color_scheme(event.scheme)
+        when EventQueue::BackgroundColorEvent
+          on_background_color(event.color)
         when EventQueue::EmptyQueueEvent
           repaint
         when Proc