tuile 0.13.0 → 0.14.0

data/sig/tuile.rbs

@@ -274,6 +274,11 @@ module Tuile
   # {Color} instances only.
   class Color
     COLOR_SYMBOLS: ::Array[Symbol]
+    CUBE_LEVELS: ::Array[Integer]
+    CUBE_INDEX: ::Array[Integer]
+    ANSI16_RGB: ::Array[::Array[Integer]]
+    ANSI16_COLORS: ::Array[Color]
+    PALETTE_COLORS: ::Array[Color]
     PALETTE_NAMES: ::Hash[Symbol, Integer]
 
     # Coerces the input to a {Color}. `nil` passes through unchanged (callers
@@ -322,6 +327,36 @@ module Tuile
     # _@param_ `target` — `:fg` or `:bg`.
     def sgr_codes: (?Symbol target) -> ::Array[Integer]
 
+    # This color as the nearest one `depth` can actually show — the
+    # degradation {Buffer#flush} applies to every color on its way to the wire:
+    # 
+    #   Color.rgb(100, 100, 100).quantize(:palette256)  # => Color.palette(241)
+    #   Color.rgb(255, 0, 0).quantize(:ansi16)          # => Color::BRIGHT_RED
+    #   Color.rgb(255, 0, 0).quantize(:truecolor)       # => itself, unchanged
+    # 
+    # Returns **the same instance** whenever `depth` shows this color as-is —
+    # every named color at every depth, a palette index anywhere but
+    # `:ansi16`, RGB at `:truecolor` — so `color.quantize(depth).equal?(color)`
+    # *is* the "needs no translating" predicate, and the common path
+    # allocates nothing.
+    # 
+    # == Implementation details
+    # 
+    # RGB picks whichever is nearer in squared-RGB distance: the 6×6×6 cube
+    # (16..231, its per-channel nearest levels being the nearest cell outright
+    # — the axes are independent) or the 24-step grey ramp (232..255, whose
+    # nearest step is the one nearest the channel mean).
+    # 
+    # Under `:ansi16` a color goes *direct* to the nearest of the 16, never
+    # via the 256-palette — two steps would compound the rounding — and the
+    # result is a *named* color, which keeps respecting the user's terminal
+    # scheme. Matching is against xterm's default RGBs for the 16, which that
+    # scheme may itself redefine: the one mapping here that can be honestly
+    # wrong.
+    # 
+    # _@param_ `depth` — one of {ColorDepth::DEPTHS}.
+    def quantize: (Symbol depth) -> Color
+
     # Full SGR escape sequence for this color (e.g. `"\e[31m"`). Useful for
     # `print`-style direct emission; for composing with other attributes use
     # {#sgr_codes} instead.
@@ -336,6 +371,30 @@ module Tuile
 
     def inspect: () -> String
 
+    # This color's RGB — the palette cell's own coordinates when the value is
+    # an index. Only ever asked of a non-Symbol value; a named color has no
+    # RGB of its own, since the terminal's scheme decides what it looks like.
+    # 
+    # _@return_ — red, green and blue, each 0..255.
+    def rgb_triple: () -> ::Array[Integer]
+
+    # Written flat — destructured rather than splatted, `x * x` rather than
+    # `x**2`, no distance helper — because it runs per style transition in
+    # {Buffer#flush}, and the tidy shape measures ~2x slower (see
+    # `benchmark/quantize.rb`).
+    # 
+    # _@param_ `rgb` — red, green and blue, each 0..255.
+    # 
+    # _@return_ — palette index, 16..255 — the nearer of this color's
+    # cube cell and its grey-ramp step. A tie goes to the cube, which spans
+    # the whole space where the ramp only covers the diagonal.
+    def nearest_palette: (::Array[Integer] rgb) -> Integer
+
+    # _@param_ `rgb` — red, green and blue, each 0..255.
+    # 
+    # _@return_ — index into {COLOR_SYMBOLS} of the nearest of the 16.
+    def nearest_ansi16: (::Array[Integer] rgb) -> Integer
+
     # The underlying raw representation — a Symbol, Integer, or frozen
     # Array<Integer>.
     attr_reader value: (Symbol | Integer | ::Array[Integer])
@@ -635,7 +694,9 @@ module Tuile
     def self.display_width: (String grapheme) -> Integer
 
     # _@param_ `size` — grid dimensions in columns × rows.
-    def initialize: (Size size) -> void
+    # 
+    # _@param_ `color_depth` — what the terminal can show — one of {ColorDepth::DEPTHS}; {#flush} degrades every emitted color to it. Validated here rather than at paint time: a bad value would otherwise surface as an exception mid-frame, far from the mistake.
+    def initialize: (Size size, ?color_depth: Symbol) -> void
 
     # _@return_ — grid dimensions.
     def size: () -> Size
@@ -796,6 +857,26 @@ module Tuile
     # _@param_ `style` — style the terminal currently holds.
     def flush_row: (String _out, Integer y, StyledString::Style style) -> StyledString::Style
 
+    # `style` as {#color_depth} can actually show it, each color through
+    # {Color#quantize}. Applied *before* the {StyledString::Style#sgr_to}
+    # diff, so two RGBs that quantize onto the same cell emit nothing at all
+    # rather than a redundant SGR.
+    # 
+    # The one-slot memo is load-bearing, not a micro-optimization: this runs
+    # per dirty *cell*, while a painted run shares one frozen
+    # {StyledString::Style} instance, so remembering just the last answer
+    # collapses the work onto actual style transitions. Without it a
+    # full-screen repaint of RGB-styled content measured 51 ms against 15 ms
+    # at `:truecolor` — a keyed cache is still the wrong answer
+    # (`D_color_depth`), but paying the arithmetic 8000 times for one span
+    # was too.
+    # 
+    # _@param_ `style`
+    # 
+    # _@return_ — `style` itself whenever nothing needed
+    # degrading — {Color#quantize}'s identity contract, extended.
+    def quantized_style: (StyledString::Style style) -> StyledString::Style
+
     # _@param_ `rect`
     # 
     # _@return_ — cells within `rect`, row-major, clamped to
@@ -860,6 +941,11 @@ module Tuile
 
     attr_reader height: Integer
 
+    # What the terminal can show ({ColorDepth::DEPTHS}). Cells hold whatever
+    # color a component painted — {#region_ansi} and friends report that,
+    # unchanged — and only {#flush} degrades it on the way to the wire.
+    attr_reader color_depth: Symbol
+
     # One screen cell: a single grapheme cluster, the {StyledString::Style} it's
     # drawn in, and a dirty flag. Mutable by design (see {Buffer} "Dirty
     # tracking") — the grid rewrites cells in place. A continuation cell (right
@@ -923,13 +1009,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
   # 
@@ -976,9 +1062,10 @@ module Tuile
     # _@param_ `content`
     def content=: (Component content) -> void
 
-    # _@return_ — currently active popup components (forwarded
-    # to {ScreenPane}). The array must not be modified!
-    def popups: () -> ::Array[Component]
+    # _@return_ — 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: () -> ::Array[Component::Overlay]
 
     # `:idle` covers *both* ends of the screen's life — before the first
     # {#run_event_loop} and after it returns — and a screen may cycle
@@ -1004,11 +1091,11 @@ module Tuile
     # _@param_ `component`
     def invalidate: (Component component) -> void
 
-    # 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.
     # 
-    # _@param_ `window`
-    def add_popup: (Component::Popup window) -> void
+    # _@param_ `window` — any overlay, modal or not.
+    def add_popup: (Component::Overlay window) -> void
 
     # Runs the event loop on the calling thread, taking over stdin (raw mode,
     # echo off): keys and mouse events are dispatched via {#handle_key} /
@@ -1069,13 +1156,13 @@ module Tuile
     # _@param_ `key`
     def unregister_global_shortcut: (String key) -> void
 
-    # 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.
     # 
-    # _@param_ `window`
-    def remove_popup: (Component::Popup window) -> void
+    # _@param_ `window` — any overlay, modal or not.
+    def remove_popup: (Component::Overlay window) -> void
 
     # Invalidates the entire attached tree, forcing every component to repaint
     # on the next cycle. Needed whenever something overdraws the scene without
@@ -1086,12 +1173,12 @@ module Tuile
     # its own, so we accept the cost of a full repaint.
     def needs_full_repaint: () -> void
 
-    # Internal — use {Component::Popup#open?} instead.
+    # Internal — use {Component::Overlay#open?} instead.
     # 
-    # _@param_ `window`
+    # _@param_ `window` — any overlay, modal or not.
     # 
-    # _@return_ — true if this popup is currently mounted.
-    def has_popup?: (Component::Popup window) -> bool
+    # _@return_ — true if this overlay is currently mounted.
+    def has_popup?: (Component::Overlay window) -> bool
 
     # Testing only — creates new screen, locks the UI, and prevents any
     # redraws, so that test TTY is not painted over. {FakeScreen#initialize}
@@ -1107,11 +1194,15 @@ module Tuile
     def self.close: () -> void
 
     # 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` — stuff to print.
     def print: (*String args) -> void
@@ -1145,23 +1236,41 @@ module Tuile
     # but only one focused.
     def cursor_position: () -> Point?
 
-    # 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_ — `:dark` or `:light`.
-    def detect_scheme: () -> Symbol
+    # 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.
+    def detect_background: () -> TerminalBackground::Result
+
+    # 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.
+    def detect_color_depth: () -> Symbol
 
     # 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` — `:dark` or `:light`.
     def on_color_scheme: (Symbol scheme) -> void
 
+    # 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`
+    def on_background_color: (Color color) -> void
+
     # 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
@@ -1236,6 +1345,16 @@ module Tuile
     # _@return_ — `:light` or `:dark`
     attr_reader color_scheme: Symbol
 
+    # 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.
+    attr_reader color_depth: Symbol
+
     # _@return_ — the back buffer components paint into
     # ({Buffer#set_text} / {Buffer#fill} / {Buffer#set_char}).
     attr_reader buffer: Buffer
@@ -1280,6 +1399,25 @@ module Tuile
     # the user toggling the OS appearance.
     attr_accessor theme_def: ThemeDef
 
+    # 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.
+    attr_reader background_color: Color?
+
     # _@return_ — the event queue.
     attr_reader event_queue: EventQueue
 
@@ -1293,7 +1431,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) }
     # 
@@ -1362,8 +1500,68 @@ module Tuile
   # any stale invalidation entries are filtered out at drain time. Subclasses
   # can paint freely in {#repaint} without re-asserting attachment.
   class Component
+    FINAL_METHODS: ::Array[Symbol]
+
+    # 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` — the class being instantiated.
+    def self.verify_final!: (Class klass) -> void
+
     def initialize: () -> void
 
+    # _@return_ — `rect.size`.
+    def size: () -> Size
+
+    # _@return_ — `rect.width`.
+    def width: () -> Integer
+
+    # _@return_ — `rect.height`.
+    def height: () -> Integer
+
+    # 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`).
+    def extent: () -> Size?
+
+    # {#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`.
+    def extent_rect: () -> Rect
+
     # _@return_ — the screen which owns this component.
     def screen: () -> Screen
 
@@ -1388,6 +1586,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
@@ -1430,8 +1633,14 @@ module Tuile
     # _@return_ — true if the paste was consumed.
     def handle_paste: (String _text) -> bool
 
-    # 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`
     def handle_mouse: (MouseEvent event) -> void
@@ -1609,6 +1818,14 @@ module Tuile
     # Children with empty rects contribute zero, since they paint nothing.
     def children_tile_rect?: () -> bool
 
+    # 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.
+    def clear_outside_extent: () -> void
+
     # Clears the background: fills every cell with a blank in the
     # {#effective_bg_color} (the terminal default when none is inherited).
     # 
@@ -1687,6 +1904,10 @@ module Tuile
     # 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`).
     attr_accessor on_theme_changed: Proc?
 
     # A scrollable list of typed items, one row each, with cursor support.
@@ -2156,6 +2377,51 @@ module Tuile
       end
     end
 
+    # A one-child region: a place in the tree reserved for content that may be
+    # absent, arrive late, or be swapped. The occupant fills the slot's {#rect}.
+    # 
+    # Wire one per region at construction, then swap occupants through
+    # {HasContent#content=} — which is how {Window} holds its footer:
+    # 
+    #   @footer_slot = Slot.new
+    #   add_child(@footer_slot)             # the region, wired once
+    #   …
+    #   @footer_slot.content = new_footer   # the occupant, swapped at will
+    # 
+    # Because the slot never leaves {Component#children}, a swap's insert index
+    # is always 0 — never a function of which *other* regions happen to be
+    # occupied, which is the whole reason to reach for one (`D_slots`).
+    # 
+    # An empty slot does not collapse: it keeps its rect and clears it, so a
+    # dialog with no message shows the hole. Close the gap with a zero extent
+    # from the parent, or assign an empty {Rect} to suppress the clear entirely
+    # (what {Window} does with an absent footer); never detach it.
+    # 
+    # Transparent to input: not {Component#focusable?},
+    # {Component#handle_mouse} descends through it, and a departing occupant's
+    # focus repair is handed to the container.
+    class Slot < Component
+      include Tuile::Component::HasContent
+
+      # _@param_ `content` — the initial occupant.
+      def initialize: (?Component? content) -> void
+
+      # Hands the repair to the container rather than doing it here: the default
+      # would move focus to `self`, and a slot is inert — no cursor, no keys,
+      # nothing to bubble from.
+      # 
+      # _@param_ `child` — the just-detached occupant.
+      def on_child_removed: (Component child) -> void
+
+      # _@param_ `content`
+      def layout: (Component content) -> void
+
+      # _@param_ `rect`
+      def rect=: (Rect rect) -> void
+
+      def on_focus: () -> void
+    end
+
     # A one-row strip of captions with exactly one of them selected — the map of
     # where the user is. Knows nothing about content: pair it with
     # {Component::TabSheet} to swap panes, or swap views yourself from
@@ -2183,7 +2449,7 @@ module Tuile
     # 
     # {Tab} handles are minted by {#add_tab} and owned by the strip. There is no
     # `items=`: a tab is identity plus its own state, so the set grows and
-    # shrinks one tab at a time. See book ch7 and `DECISIONS.md` `D-tabs`.
+    # shrinks one tab at a time. See book ch7 and `DECISIONS.md` `D_tabs`.
     # 
     # == Sizing
     # Assign a {#rect} (typically from the surrounding {Layout}). One wider than
@@ -2269,7 +2535,7 @@ module Tuile
       # blank tail — or on a lower row, when the rect is taller than one —
       # selects nothing. It still *focuses*: {Component#handle_mouse}'s
       # click-to-focus is ungated by geometry.
-      def extent: () -> Rect
+      def extent: () -> Size
 
       # Switches tabs on LEFT / RIGHT, consuming the key even at the ends of the
       # strip (the selection clamps). Every other key is left unhandled so it
@@ -2517,130 +2783,65 @@ module Tuile
       attr_accessor bg: (Color | Symbol | Integer | ::Array[Integer])?
     end
 
-    # An overlay that wraps any {Component} as its content. Popup itself
-    # paints nothing — it's a transparent host that handles its lifecycle
-    # ({#open} / {#close} / {#open?}, ESC/q to close) and holds a top-down
-    # {#size} the {Screen} applies.
-    # 
-    # The popup does *not* size itself to its content. Its box is declared by
-    # {#size} — a {Fraction} (resolved against the screen every layout pass, so
-    # it tracks resize) or an absolute {Size} (clamped to the screen). The
-    # default is {Fraction::HALF}: half the screen, centered. The wrapped
-    # content then fills that box and handles its own overflow by wrapping and
-    # scrolling, so use content that can — a {Component::TextView} or
-    # {Component::TextArea} — for anything longer than fits. A
-    # {Component::Label} only truncates.
-    # 
-    # Modal by default: it centers on the screen, grabs focus, eats keys, and
-    # blocks clicks beneath it. Pass `modal: false` for a non-modal overlay
-    # that floats above the content without taking focus or capturing input —
-    # the caller positions it (via {#rect=}), sizes it, and drives it from app
-    # code. That's the building block for an autocomplete/slash-command list
-    # anchored to a text field's caret: typing keeps focus in the input while
-    # the caller refills and drives the overlay.
-    # 
-    # The wrapped content fills the popup's full {#rect}; if you want a frame
-    # and caption, wrap a {Component::Window} (or any subclass — including
-    # {Component::LogWindow}) and let it draw its own border:
+    # A modal dialog: an {Component::Overlay} that centers itself on the screen,
+    # grabs focus, scopes keys to its own subtree, blocks clicks beneath it, and
+    # closes on ESC or `q`.
     # 
     #   window = Component::Window.new("Help")
     #   window.content = Component::List.new.tap { _1.lines = lines }
     #   Component::Popup.new(content: window).open
     # 
     # Bare content also works (a {Component::Label}, a {Component::List}…), in
-    # which case the popup is borderless.
+    # which case the popup is borderless. For a floating layer that does *not*
+    # take focus or capture input — an autocomplete list anchored to a field, a
+    # toast — use {Component::Overlay} directly.
+    # 
+    # The popup does *not* size itself to its content. Its box is set by
+    # {#declared_size} — a {Fraction} (resolved against the screen every layout
+    # pass, so it tracks resize) or an absolute {Size} (clamped to the screen).
+    # The default is {Fraction::HALF}: half the screen, centered. The wrapped content
+    # then fills that box and handles its own overflow by wrapping and scrolling,
+    # so use content that can — a {Component::TextView} or
+    # {Component::TextArea} — for anything longer than fits. A
+    # {Component::Label} only truncates.
+    # 
+    # == Implementation details
     # 
     # `q` and ESC close the popup — handled here, at the top of the popup's own
     # subtree, so the key only arrives after every component on the focus chain
     # declined it (see {ScreenPane#handle_key}). That's why typing `q` into a
-    # nested {Component::TextField} doesn't dismiss the popup: the field
-    # consumes it first.
+    # nested {Component::TextField} doesn't dismiss the popup: the field consumes
+    # it first.
     # 
-    # A left click *outside* the popup closes it too, modal or not — see
-    # {#close_on_outside_click?} for the exact contract and {#on_close=} for
-    # the notice a driver hears when it happens.
-    class Popup < Component
-      include Tuile::Component::HasContent
-
+    # A left click *outside* the popup closes it too — see
+    # {Overlay#close_on_outside_click?} for the exact contract and
+    # {Overlay#on_close=} for the notice a driver hears when it happens.
+    # 
+    # UI-thread-confined, like every component (see {Screen}).
+    class Popup < Tuile::Component::Overlay
       # _@param_ `content` — initial content; can be set later via {#content=}. The content fills the popup's {#rect}; it does not determine the popup's size.
       # 
-      # _@param_ `modal` — true (default) for a centered, focus-grabbing, input-capturing modal; false for a non-modal overlay the caller positions and drives (see the class docs).
+      # _@param_ `declared_size` — the popup's box, applied top-down. A {Fraction} is resolved against the screen each layout pass; a {Size} is clamped to the screen. Defaults to {Fraction::HALF}.
       # 
-      # _@param_ `size` — the popup's size, applied top-down. A {Fraction} is resolved against the screen each layout pass; a {Size} is clamped to the screen. Defaults to {Fraction::HALF}.
-      # 
-      # _@param_ `close_on_outside_click` — true (default) to dismiss on a left click that misses this popup. See {#close_on_outside_click?}.
-      def initialize: (
-                        ?content: Component?,
-                        ?modal: bool,
-                        ?size: (Size | Fraction),
-                        ?close_on_outside_click: bool
-                      ) -> void
+      # _@param_ `close_on_outside_click` — true (default) to dismiss on a left click that misses this popup. See {Overlay#close_on_outside_click?}.
+      def initialize: (?content: Component?, ?declared_size: (Size | Fraction), ?close_on_outside_click: bool) -> void
 
-      # _@return_ — whether this popup is modal. See {#initialize}.
+      # _@return_ — true — a Popup scopes key dispatch, grabs focus on
+      # open, and blocks clicks on the content beneath it.
       def modal?: () -> bool
 
-      # Whether a left click outside this popup closes it (default true, modal or
-      # not). The pane does the closing — {ScreenPane#handle_mouse} snapshots
-      # the open popups *before* routing the click and closes the dismissable
-      # ones *after*, so a widget that toggles its own overlay from a click on
-      # its face (a {Component::Select}, a {Component::MenuBar} title) still
-      # toggles correctly: the delivered click closes the overlay and the
-      # dismissal then no-ops on it, rather than closing and reopening it. Only
-      # `:left` dismisses; scroll and right clicks never do.
-      # 
-      # **"Outside" spans the {#owner} chain, not just this rect.** A click
-      # counts as inside this popup when it lands in its rect *or* in any popup
-      # that belongs to it — so a dialog is not dismissed by a click on a
-      # dropdown its own field opened, and a menu cascade is not dismissed by a
-      # click on one of its deeper panels. Popups with no owner relationship are
-      # independent: clicking one dismisses the other, which is what a
-      # window-like overlay should do. A popup that must survive unrelated
-      # clicks entirely ({Component::Notification}) sets this false.
-      # 
-      # Every dismissable popup closes, not just the topmost, and stacking order
-      # plays no part: a {Component::MenuBar} cascade must vanish whole on one
-      # click on the background, not peel one panel per click.
-      def close_on_outside_click?: () -> bool
-
+      # _@return_ — true — {ScreenPane#add_popup} focuses a popup on open,
+      # and focus repair falls back to it when its subtree has no tab stop.
       def focusable?: () -> bool
 
-      # Reassigns the popup's rect, escalating to a full scene repaint when an
-      # open popup shrinks or moves so its new rect no longer covers the cells
-      # it previously painted. A popup overdraws the scene without clipping and
-      # nothing clears underneath it, so {Screen#repaint}'s popup-only fast path
-      # would repaint into the new rect and leave the vacated cells showing
-      # stale content. When the new rect fully covers the old one (the popup
-      # only grew), the fast path is correct and the full repaint is skipped.
-      # 
-      # _@param_ `new_rect`
-      def rect=: (Rect new_rect) -> void
-
-      # Mounts this popup on the {Screen}, re-resolving its {#size} against the
-      # current screen first.
-      # 
-      #   popup = Component::Popup.new(content: window).open   # construct and mount
-      # 
-      # There is deliberately no class-level `Popup.open` factory — see
-      # `DECISIONS.md` `D-popup-open`; returning `self` is what keeps the
-      # one-liner above available without one.
-      def open: () -> self
-
-      # Removes this popup from the {Screen}. No-op if not currently open.
-      def close: () -> void
-
-      # _@return_ — true if this popup is currently mounted on the screen.
-      def open?: () -> bool
-
-      # Re-resolves {#size} against the current screen and repositions the popup
-      # *itself* (this is not laying out content — the popup's own rect): a
-      # modal popup recenters; a non-modal overlay keeps its caller-assigned
-      # top-left (only its size follows the screen). Called on {#open}, on
-      # {#size=}, and by the screen's layout pass (so a {Fraction} size tracks
-      # SIGWINCH).
+      # Re-resolves {#declared_size} against the current screen and recenters the popup
+      # *itself* (this is not laying out content — the popup's own rect). Called
+      # on {Overlay#open}, on {#declared_size=}, and by the screen's layout pass,
+      # so a {Fraction} tracks SIGWINCH.
       # 
-      # The final rect is computed and assigned in one step rather than sizing
-      # at the origin and then centering: the intermediate origin rect rarely
-      # covers the previous one, which would make {#rect=}'s shrink/move
+      # The final rect is computed and assigned in one step rather than sizing at
+      # the origin and then centering: the intermediate origin rect rarely covers
+      # the previous one, which would make {Overlay#rect=}'s shrink/move
       # detection fire a full repaint on every resize.
       def reposition: () -> void
 
@@ -2656,53 +2857,14 @@ module Tuile
       # _@return_ — true if the key was handled.
       def handle_key: (String key) -> bool
 
-      # Fires {#on_close}. A subclass overriding this **must** call `super`, or
-      # the popup's driver never hears that it closed.
-      def on_detached: () -> void
-
-      # Content fills the popup's full rect — Popup has no border to subtract.
+      # The box this popup asks for, *as set* — a {Fraction} comes back
+      # unresolved. {#rect} is the resolved answer. Named apart from `size`
+      # because a component's `size` is its `rect.size`, which this is not: it
+      # is an input re-read on every layout pass, not a report of the current
+      # geometry.
       # 
-      # _@param_ `content`
-      def layout: (Component content) -> void
-
-      # _@param_ `event`
-      def handle_mouse: (MouseEvent event) -> void
-
-      def on_focus: () -> void
-
-      # _@return_ — the popup's declared size. See {#size=}.
-      attr_accessor size: (Size | Fraction)
-
-      # _@return_ — see {#close_on_outside_click?}.
-      attr_writer close_on_outside_click: bool
-
-      # The component this overlay is *part of*, or `nil` (the default) when it
-      # is an overlay in its own right. It exists for outside-click dismissal:
-      # a click inside this popup also counts as inside whatever popup encloses
-      # its owner, so the host is not dismissed by a click on a panel it put
-      # there. See {#close_on_outside_click?}.
-      # 
-      # Set it to the *driver* — {Component::ComboBox} hands its dropdown
-      # `self` — rather than to the enclosing popup: the driver knows what it
-      # is, while the popup above it is a tree relationship the pane resolves
-      # at click time (so it cannot go stale). Any {Component} is accepted, and
-      # a `Popup` resolves to itself, which is how a
-      # {Component::MenuBar::Cascade} chains each panel to the one it dropped
-      # out of.
-      attr_accessor owner: Component?
-
-      # A callback taking no arguments, fired once this popup has left the
-      # screen — **however it left**: {#close}, a direct {Screen#remove_popup},
-      # an outside click, or teardown via {Screen#close}. That unconditionality
-      # is the point, so it hangs off {#on_detached} rather than {#close}; a
-      # driver keeping its own record of open popups reconciles it here and
-      # cannot drift ({Component::MenuBar::Cascade} is the worked example).
-      # 
-      # It fires *after* the popup is detached, so {#open?} is already false and
-      # the usual {Component#on_detached} caveats apply: release state, don't
-      # inspect the tree, keep it trivial (it may run while the pane is mid-way
-      # through closing a batch of popups, and a raise propagates).
-      attr_accessor on_close: Proc?
+      # _@return_ — see {#declared_size=}.
+      attr_accessor declared_size: (Size | Fraction)
     end
 
     # A clickable button. Activated by Enter, Space, or a left mouse click;
@@ -2738,7 +2900,7 @@ module Tuile
       # It still *focuses*: {Component#handle_mouse}'s click-to-focus is ungated
       # by geometry. Same rule as {Checkbox#extent}, which documents the two
       # traps behind it.
-      def extent: () -> Rect
+      def extent: () -> Size
 
       # Fires {#on_click} on a left click within {#extent}; `super` runs first, so
       # a click anywhere in {#rect} still focuses.
@@ -2801,11 +2963,6 @@ module Tuile
       # _@param_ `child`
       def remove: (Component child) -> void
 
-      # Dispatches the event to the child under the mouse cursor.
-      # 
-      # _@param_ `event`
-      def handle_mouse: (MouseEvent event) -> void
-
       def on_focus: () -> void
 
       # How much space a child gets along one axis of a {Box}: exactly {#cells},
@@ -3237,7 +3394,7 @@ module Tuile
     # Home/End are declined too, so they stay available app-wide.
     # 
     # There is no type-ahead: a hidden prefix buffer *is* the ComboBox query with
-    # the feedback removed (`DECISIONS.md` `D-select`). Which is also why labels
+    # the feedback removed (`DECISIONS.md` `D_select`). Which is also why labels
     # need no prefix-disambiguation.
     # 
     # == Implementation details
@@ -3284,7 +3441,15 @@ module Tuile
       # _@param_ `key`
       def handle_key: (String key) -> bool
 
-      # Toggles the dropdown on a left click anywhere in {#rect} — a field's
+      # The one row this Select paints — the full width, at the top of {#rect}.
+      # A single-slot container ({Component::Window}, {Component::Popup}) hands
+      # its content the whole inner rect, so a Select is routinely assigned more
+      # height than it uses; {#repaint} clears that tail, {#handle_mouse} refuses
+      # clicks in it, and the dropdown hangs under this rather than under the
+      # unused space.
+      def extent: () -> Size
+
+      # Toggles the dropdown on a left click anywhere in {#extent} — a field's
       # affordance is its whole row, as the well advertises; `super` runs first,
       # so the click also focuses.
       # 
@@ -3353,7 +3518,7 @@ module Tuile
       # a read-only display field could override back to `false`. Only
       # `focusable?` lives here — `tab_stop?` diverges between leaf fields and
       # composing wrappers, so it stays per-class (`DECISIONS.md`
-      # `D-integer-field`).
+      # `D_integer_field`).
       def focusable?: () -> bool
 
       # _@return_ — the options.
@@ -3383,8 +3548,18 @@ module Tuile
 
       def focusable?: () -> bool
 
-      # _@param_ `event`
-      def handle_mouse: (MouseEvent event) -> void
+      # _@return_ — optional focusable component occupying the
+      # bottom border row, always spanning the full inner width.
+      def footer: () -> Component?
+
+      # Mounts a component in the bottom border row, spanning the full inner
+      # width and positioned automatically; `nil` removes it.
+      # 
+      # Precedence: a footer component present hides {#footer_text}; absent, the
+      # text embeds into the bottom border. No window needs both at once.
+      # 
+      # _@param_ `new_footer`
+      def footer=: (Component? new_footer) -> void
 
       # _@param_ `new_rect`
       def rect=: (Rect new_rect) -> void
@@ -3435,9 +3610,12 @@ module Tuile
       # _@param_ `fg` — the active-border color, or nil when inactive.
       def bottom_border: (Integer inner_w, Color? fg) -> StyledString
 
-      # Positions the footer over the bottom border row, spanning the full
+      # Positions the footer slot over the bottom border row, spanning the full
       # inner width (the only dimension a bottom-row widget needs — the window
       # already knows it).
+      # 
+      # An unoccupied slot gets an *empty* rect, not the row — a {Slot} clears
+      # whatever it is given, which would blank the border underneath.
       def layout_footer: () -> void
 
       # Read through *this* method, never `@caption` — the ivar stays nil until
@@ -3455,16 +3633,168 @@ module Tuile
 
       def on_focus: () -> void
 
-      # _@return_ — optional focusable component occupying the
-      # bottom border row, always spanning the full inner width.
-      attr_accessor footer: Component?
-
       # _@return_ — optional chrome embedded into the bottom border
       # line, mirroring {#caption} on the top line. Empty by default; hidden
       # whenever a {#footer} component is present.
       attr_accessor footer_text: (StyledString | String)?
     end
 
+    # A component mounted on the {Screen}'s overlay stack rather than in the
+    # tiled tree: it floats above the content at a rect the caller assigns, and
+    # has an open/close lifecycle instead of a parent that lays it out.
+    # 
+    #   overlay = Component::Overlay.new(content: Component::Label.new("saved"))
+    #   overlay.rect = Rect.new(10, 4, 20, 1)   # you place it — nothing else does
+    #   overlay.open                            # mounts it on the Screen
+    #   overlay.close
+    # 
+    # That is the whole of it — floating, plus the lifecycle, {#on_close},
+    # outside-click dismissal and {#owner}. {Component::Popup} is the subclass
+    # that adds a declared size, self-centering, focus and key handling.
+    # 
+    # The wrapped content fills the overlay's whole {#rect}; for a frame and a
+    # caption, wrap a {Component::Window} and let it draw its own border.
+    # 
+    # == Implementation details
+    # 
+    # **{#focusable?} and {#modal?} move together — flip both or neither.** The
+    # defaults here are inert (`false`, `false`): a bare overlay floats without
+    # disturbing focus or key dispatch. {Component::Popup} flips both. What must
+    # not appear is a *focusable non-modal* overlay: {ScreenPane#handle_key}
+    # scopes delivery to the topmost modal popup or else the tiled content, so
+    # such an overlay would hold focus outside the key scope, where delivery
+    # reaches nobody and *every* keystroke goes dead until Tab recovers. A
+    # non-modal overlay is therefore driven from its owner's key handler
+    # ({Component::Select} forwarding to its dropdown) instead of claiming focus.
+    # 
+    # **A derived position needs a {#reposition} override.** The default is a
+    # no-op: the rect is whatever the caller last assigned. An overlay whose
+    # position is computed — from the screen, or from an anchor — must recompute
+    # it there, or it keeps a stale rect after a SIGWINCH and sits off-screen
+    # entirely if the terminal narrowed. Closing on resize is equally legal
+    # ({Component::MenuBar} drops its cascade from `rect=` rather than walking
+    # every level to re-anchor it).
+    # 
+    # UI-thread-confined, like every component (see {Screen}).
+    class Overlay < Component
+      include Tuile::Component::HasContent
+
+      # _@param_ `content` — initial content; can be set later via {#content=}. It fills the overlay's {#rect} and does not determine it.
+      # 
+      # _@param_ `close_on_outside_click` — true (default) to dismiss on a left click that misses this overlay. See {#close_on_outside_click?}.
+      def initialize: (?content: Component?, ?close_on_outside_click: bool) -> void
+
+      # _@return_ — false — a bare overlay scopes no keys and blocks no
+      # clicks. {Component::Popup} overrides it, together with {#focusable?}.
+      def modal?: () -> bool
+
+      # _@return_ — false — a bare overlay leaves focus where it was. See
+      # the class docs: override it only together with {#modal?}.
+      def focusable?: () -> bool
+
+      # _@return_ — false — Tab never lands on the overlay wrapper itself
+      # (its content may still carry stops).
+      def tab_stop?: () -> bool
+
+      # Whether a left click outside this overlay closes it (default true). The
+      # pane does the closing — {ScreenPane#handle_mouse} snapshots the open
+      # overlays *before* routing the click and closes the dismissable ones
+      # *after*, so a widget that toggles its own overlay from a click on its
+      # face (a {Component::Select}, a {Component::MenuBar} title) still toggles
+      # correctly: the delivered click closes the overlay and the dismissal then
+      # no-ops on it, rather than closing and reopening it. Only `:left`
+      # dismisses; scroll and right clicks never do.
+      # 
+      # **"Outside" spans the {#owner} chain, not just this rect.** A click
+      # counts as inside this overlay when it lands in its rect *or* in any
+      # overlay that belongs to it — so a dialog is not dismissed by a click on a
+      # dropdown its own field opened, and a menu cascade is not dismissed by a
+      # click on one of its deeper panels. Overlays with no owner relationship
+      # are independent: clicking one dismisses the other, which is what a
+      # window-like overlay should do. One that must survive unrelated clicks
+      # entirely ({Component::Notification}) sets this false.
+      # 
+      # Every dismissable overlay closes, not just the topmost, and stacking
+      # order plays no part: a {Component::MenuBar} cascade must vanish whole on
+      # one click on the background, not peel one panel per click.
+      def close_on_outside_click?: () -> bool
+
+      # Reassigns the overlay's rect, escalating to a full scene repaint when an
+      # open overlay shrinks or moves so its new rect no longer covers the cells
+      # it previously painted. An overlay overdraws the scene without clipping
+      # and nothing clears underneath it, so {Screen#repaint}'s overlay-only fast
+      # path would repaint into the new rect and leave the vacated cells showing
+      # stale content. When the new rect fully covers the old one (the overlay
+      # only grew), the fast path is correct and the full repaint is skipped.
+      # 
+      # _@param_ `new_rect`
+      def rect=: (Rect new_rect) -> void
+
+      # Mounts this overlay on the {Screen}.
+      # 
+      #   overlay = Component::Overlay.new(content: label).open   # construct and mount
+      # 
+      # There is deliberately no class-level `Overlay.open` factory — see
+      # `DECISIONS.md` `D_popup_open`; returning `self` is what keeps the
+      # one-liner above available without one.
+      def open: () -> self
+
+      # Removes this overlay from the {Screen}. No-op if not currently open.
+      def close: () -> void
+
+      # _@return_ — true if this overlay is currently mounted on the screen.
+      def open?: () -> bool
+
+      # Recomputes this overlay's own rect (not its content's layout). A no-op
+      # here — the rect is whatever the caller assigned — and the hook a subclass
+      # with a *derived* position overrides; see the class docs. Called on
+      # {#open} and by the screen's layout pass, so an override tracks SIGWINCH.
+      def reposition: () -> void
+
+      # Fires {#on_close}. A subclass overriding this **must** call `super`, or
+      # the overlay's driver never hears that it closed.
+      def on_detached: () -> void
+
+      # Content fills the overlay's full rect — an Overlay has no border to
+      # subtract.
+      # 
+      # _@param_ `content`
+      def layout: (Component content) -> void
+
+      def on_focus: () -> void
+
+      # _@return_ — see {#close_on_outside_click?}.
+      attr_writer close_on_outside_click: bool
+
+      # The component this overlay is *part of*, or `nil` (the default) when it
+      # is an overlay in its own right. It exists for outside-click dismissal: a
+      # click inside this overlay also counts as inside whatever overlay encloses
+      # its owner, so the host is not dismissed by a click on a panel it put
+      # there. See {#close_on_outside_click?}.
+      # 
+      # Set it to the *driver* — {Component::ComboBox} hands its dropdown `self`
+      # — rather than to the enclosing overlay: the driver knows what it is,
+      # while the overlay above it is a tree relationship the pane resolves at
+      # click time (so it cannot go stale). Any {Component} is accepted, and an
+      # `Overlay` resolves to itself, which is how a
+      # {Component::MenuBar::Cascade} chains each panel to the one it dropped out
+      # of.
+      attr_accessor owner: Component?
+
+      # A callback taking no arguments, fired once this overlay has left the
+      # screen — **however it left**: {#close}, a direct {Screen#remove_popup},
+      # an outside click, or teardown via {Screen#close}. That unconditionality
+      # is the point, so it hangs off {#on_detached} rather than {#close}; a
+      # driver keeping its own record of open overlays reconciles it here and
+      # cannot drift ({Component::MenuBar::Cascade} is the worked example).
+      # 
+      # It fires *after* the overlay is detached, so {#open?} is already false
+      # and the usual {Component#on_detached} caveats apply: release state, don't
+      # inspect the tree, keep it trivial (it may run while the pane is mid-way
+      # through closing a batch of overlays, and a raise propagates).
+      attr_accessor on_close: Proc?
+    end
+
     # A boolean input on one row. Space, Enter or a left click toggles it:
     # 
     #   [x] Enable syslog forwarding
@@ -3547,7 +3877,7 @@ module Tuile
       # The extent ignores {Component#bg_color}: an inherited tint paints the dead
       # tail, but a hit test that silently widened with a background would be a
       # mode switch invisible in the code and untestable by inspection.
-      def extent: () -> Rect
+      def extent: () -> Size
 
       # Toggles on Space or Enter. Every other key is left unhandled so it bubbles
       # to an ancestor.
@@ -3589,7 +3919,7 @@ module Tuile
       # a read-only display field could override back to `false`. Only
       # `focusable?` lives here — `tab_stop?` diverges between leaf fields and
       # composing wrappers, so it stays per-class (`DECISIONS.md`
-      # `D-integer-field`).
+      # `D_integer_field`).
       def focusable?: () -> bool
     end
 
@@ -3634,7 +3964,7 @@ module Tuile
     # {Item} handles are minted by {#add_item} and nest via the *same* method, so
     # depth is unlimited. There is no removal, no reordering and no dynamic
     # rebuilding: a menu is built once, at construction. See `DECISIONS.md`
-    # `D-menu-bar`.
+    # `D_menu_bar`.
     # 
     # == Sizing
     # Assign a {#rect} (typically one {Layout::Fixed}`[1]` row at the top of a
@@ -3697,7 +4027,7 @@ module Tuile
       # tail — or on a lower row, when the rect is taller than one — opens
       # nothing. It still *focuses*: {Component#handle_mouse}'s click-to-focus is
       # ungated by geometry.
-      def extent: () -> Rect
+      def extent: () -> Size
 
       # _@param_ `new_rect`
       def rect=: (Rect new_rect) -> void
@@ -3970,7 +4300,7 @@ module Tuile
       # 
       # Widths are measured here, per level — the panel is as wide as the level's
       # widest label — because {ListDropdown} deliberately measures nothing
-      # itself (`DECISIONS.md` `D-select`).
+      # itself (`DECISIONS.md` `D_select`).
       # 
       # == Implementation details
       # While open it consumes **everything** except the two keys that mean
@@ -4094,7 +4424,7 @@ module Tuile
     #   combo.value = some_user                       # selects it; field shows its label
     # 
     # It's the assembly you'd otherwise wire by hand — a {TextField} plus a
-    # non-modal {Popup} over a {List} — promoted to one component. Give it a
+    # an {Overlay} over a {List} — promoted to one component. Give it a
     # single-row {#rect}; it paints the field across that row with a `▾` in the
     # last column and floats the dropdown above or below.
     # 
@@ -4149,6 +4479,12 @@ module Tuile
 
       def repaint: () -> void
 
+      # The one row this combo paints — the full width, at the top of {#rect}.
+      # A single-slot container hands its content the whole inner rect, so a
+      # ComboBox is routinely assigned more height than it uses; the dropdown
+      # hangs under this rather than under the unused space below it.
+      def extent: () -> Size
+
       # Field spans the row bar the last column, which the `▾` occupies
       # ({HasContent} layout hook). One row, or none at all when the combo itself
       # was given none — a starved parent must not hand out a rect it doesn't own.
@@ -4231,7 +4567,7 @@ module Tuile
       # a read-only display field could override back to `false`. Only
       # `focusable?` lives here — `tab_stop?` diverges between leaf fields and
       # composing wrappers, so it stays per-class (`DECISIONS.md`
-      # `D-integer-field`).
+      # `D_integer_field`).
       def focusable?: () -> bool
 
       def on_focus: () -> void
@@ -4287,7 +4623,7 @@ module Tuile
       # a read-only display field could override back to `false`. Only
       # `focusable?` lives here — `tab_stop?` diverges between leaf fields and
       # composing wrappers, so it stays per-class (`DECISIONS.md`
-      # `D-integer-field`).
+      # `D_integer_field`).
       def focusable?: () -> bool
 
       # _@return_ — one-arg callable fired with the new value
@@ -4402,12 +4738,6 @@ module Tuile
       # _@param_ `new_rect`
       def rect=: (Rect new_rect) -> void
 
-      # Forwards to whichever child the click landed on — the strip's row, or
-      # the pane below it.
-      # 
-      # _@param_ `event`
-      def handle_mouse: (MouseEvent event) -> void
-
       # Sends focus to the strip: a sheet is a container, and the strip is where
       # a tab switch is driven from. The pane is a Tab press away.
       def on_focus: () -> void
@@ -5281,42 +5611,23 @@ module Tuile
       end
     end
 
-    # Shows a log. Construct your logger pointed at a {LogWindow::IO} to route
-    # log lines into this window:
+    # A {Window} framing a {LogTextView} — the framed log pane. All the log
+    # behavior lives on the view (see {LogTextView} for the adapter and the
+    # wrap rationale); the window adds the border, caption and delegation:
     # 
     #   log_window = Tuile::Component::LogWindow.new
     #   logger = Logger.new(Tuile::Component::LogWindow::IO.new(log_window))
-    # 
-    # Any logger that writes formatted lines to an IO works the same way —
-    # for example `TTY::Logger` configured with the `:console` handler and
-    # `output: LogWindow::IO.new(window)`.
     class LogWindow < Tuile::Component::Window
+      IO: Class
+
       # _@param_ `caption`
       def initialize: (?String caption) -> void
 
-      # Appends given line to the log. Can be called from any thread. Does nothing if nil is passed in.
+      # Appends the given line to the log, from any thread — delegates to
+      # {LogTextView#log}.
       # 
-      # _@param_ `string` — the line (or multiple lines) to log.
+      # _@param_ `string` — the line (or multiple lines) to log; `nil` is a no-op.
       def log: (String? string) -> void
-
-      # IO-shaped adapter that forwards each log line to the owning {LogWindow}.
-      # Implements both {#write} (stdlib `Logger`) and {#puts} (loggers that
-      # call `output.puts`, e.g. `TTY::Logger`).
-      class IO
-        # _@param_ `window`
-        def initialize: (LogWindow window) -> void
-
-        # _@param_ `string`
-        def write: (String string) -> void
-
-        # _@param_ `string`
-        def puts: (String string) -> void
-
-        # Stdlib `Logger` only treats an object as an IO target when it
-        # responds to both {#write} and {#close}; otherwise it tries to
-        # interpret it as a filename. This is a no-op.
-        def close: () -> void
-      end
     end
 
     # A single-line text input with a real hardware caret, scrolling
@@ -5588,12 +5899,9 @@ module Tuile
       # a read-only display field could override back to `false`. Only
       # `focusable?` lives here — `tab_stop?` diverges between leaf fields and
       # composing wrappers, so it stays per-class (`DECISIONS.md`
-      # `D-integer-field`).
+      # `D_integer_field`).
       def focusable?: () -> bool
 
-      # _@param_ `event`
-      def handle_mouse: (MouseEvent event) -> void
-
       # _@param_ `rect`
       def rect=: (Rect rect) -> void
 
@@ -5634,13 +5942,29 @@ module Tuile
       def caption=: ((String | StyledString)? new_caption) -> void
     end
 
-    # A mixin interface for a component with one child tops. The host must
-    # provide a protected `layout(content)` method which repositions the
-    # content component; the mixin manages `@content` itself.
+    # A component that owns exactly one child *directly*, under the name
+    # `content`. The includer initializes `@content` to nil and provides a
+    # protected `layout(content)` positioning the child; the mixin owns the swap:
+    # 
+    #   class Slot < Component
+    #     include Component::HasContent
+    # 
+    #     def initialize = (super; @content = nil)
+    # 
+    #     protected
+    # 
+    #     def layout(content) = content.rect = rect
+    #   end
+    # 
+    # Include it when the child is **permanent and integral** — a typed field's
+    # inner {TextField}, an {Overlay}'s body. It does *not* mean "a component
+    # with one child": an includer may hold others alongside, as {Window} does
+    # with its footer. For a region an app swaps, hold a {Slot} instead.
+    # 
+    # A tree walk finds content generically through `is_a?(HasContent)` plus a
+    # `content` compare, which is why this is a mixin rather than a per-class
+    # accessor — the same reason {HasCaption} is one.
     module HasContent
-      # _@param_ `event`
-      def handle_mouse: (MouseEvent event) -> void
-
       # _@param_ `rect`
       def rect=: (Rect rect) -> void
 
@@ -5650,27 +5974,46 @@ module Tuile
       attr_accessor content: Component?
     end
 
-    # A {Window} preconfigured with a {List} of static lines. Useful for
-    # showing read-only information.
+    # A {Window} with a read-only body, in one of two presentations:
+    # **prose** ({#message=}) wraps in a scrollable {TextView}, **rows**
+    # ({#lines=}) stay one per row in a {List}, truncating instead of
+    # wrapping — the presentation for columnar output, where a wrap would
+    # destroy the alignment. Usable tiled (add it to a {Layout}) or as a
+    # popup via {.open}; the constructor and {.open} pick the presentation
+    # from the body's type:
     # 
-    # Usable tiled (just add to a {Layout}) or as a popup via {.open}, which
-    # wraps it in a {Popup}.
+    #   Component::InfoWindow.open("Help", "A long explanation, wrapped to fit.")
+    #   Component::InfoWindow.open("Files", ["drwx  src/", "-rw-  README.md"])
+    # 
+    # Both write the same body slot — the last writer wins.
     class InfoWindow < Tuile::Component::Window
-      # _@param_ `caption`
+      # _@param_ `caption` — the border title.
       # 
-      # _@param_ `lines` — initial content; each entry may contain Rainbow formatting.
-      def initialize: (?String caption, ?::Array[String] lines) -> void
+      # _@param_ `body` — an `Array` is assigned through {#lines=}, anything else through {#message=}.
+      def initialize: (?(String | StyledString)? caption, ?(String | StyledString | Component | ::Array[untyped])? body) -> void
+
+      # Sets the rows body: a {List} populated via {List#lines=} (so entries
+      # are coerced, `\n`-split and rstripped exactly as there), one item per
+      # row, long rows truncated — never wrapped. For prose use {#message=}.
+      # 
+      # _@param_ `lines` — entries are `String`, `StyledString`, or anything that responds to `#to_s`.
+      def lines=: (::Array[untyped] lines) -> void
 
       # Opens the info window as a popup.
       # 
-      # _@param_ `caption`
+      # _@param_ `caption` — the border title.
       # 
-      # _@param_ `lines` — the content, may contain formatting.
+      # _@param_ `body` — dispatched by type as in {#initialize}.
       # 
-      # _@param_ `size` — the popup's size, applied top-down; the list wraps and scrolls within it. Defaults to {Fraction::HALF}.
+      # _@param_ `declared_size` — the popup's box, applied top-down; the body wraps or scrolls within it. Defaults to {Fraction::HALF}.
       # 
       # _@return_ — the opened popup.
-      def self.open: (String caption, ::Array[String] lines, ?size: (Size | Fraction)) -> Popup
+      def self.open: ((String | StyledString)? caption, ?(String | StyledString | Component | ::Array[untyped])? body, ?declared_size: (Size | Fraction)) -> Popup
+
+      # _@return_ — whatever {#message=}
+      # was given — set a `String`, read that `String` back. After
+      # {#lines=} it is the {List} that setter mounted.
+      attr_accessor message: (String | StyledString | Component)?
     end
 
     # Single-select from a set of typed items, one row each. Arrows move a
@@ -5811,12 +6154,9 @@ module Tuile
       # a read-only display field could override back to `false`. Only
       # `focusable?` lives here — `tab_stop?` diverges between leaf fields and
       # composing wrappers, so it stays per-class (`DECISIONS.md`
-      # `D-integer-field`).
+      # `D_integer_field`).
       def focusable?: () -> bool
 
-      # _@param_ `event`
-      def handle_mouse: (MouseEvent event) -> void
-
       # _@param_ `rect`
       def rect=: (Rect rect) -> void
 
@@ -5853,22 +6193,23 @@ module Tuile
     # (floor {MIN_CAP_WIDTH}) and {HEIGHT_FRACTION} tall, and **grows but never
     # shrinks** while it lives; a long message wraps to {MAX_ROWS_PER_MESSAGE}
     # rows and is then ellipsized, and entries past the height cap wait unpainted.
-    # `DECISIONS.md` `D-notification` has why each of those is what it is.
+    # `DECISIONS.md` `D_notification` has why each of those is what it is.
     # 
     # Three things it deliberately doesn't do:
     # 
-    # - **Take focus, or receive keys.** A non-modal popup sits off the
-    #   key-dispatch scope ({ScreenPane#handle_key}), so not even {Popup}'s
-    #   `q`/ESC arrives here. A left click *on the box* dismisses
-    #   ({#handle_mouse}); an app wanting a key registers a global shortcut and
-    #   calls {#close}. A click *elsewhere* does not — this is the one popup
-    #   with {Popup#close_on_outside_click?} false, since a toast is timed and
-    #   an unrelated click is not about it.
+    # - **Take focus, or receive keys.** An {Overlay} sits off the
+    #   key-dispatch scope ({ScreenPane#handle_key}), so no key arrives here at
+    #   all. A left click *on the box* dismisses ({#handle_mouse}); an app
+    #   wanting a key registers a global shortcut and calls {Overlay#close}. A
+    #   click *elsewhere* does not — this is the one overlay with
+    #   {Overlay#close_on_outside_click?} false, since a toast is timed and an
+    #   unrelated click is not about it.
     # - **Follow a theme flip.** A `Theme::Ref` `color:` is resolved once, when
     #   the message is added — a toast lives seconds, so there is no
     #   {Component#on_theme_changed} rebuild.
-    # - **Take a size.** {#size=} raises; the messages decide.
-    class Notification < Tuile::Component::Popup
+    # - **Take a size.** An {Overlay} has no declared box; the messages decide
+    #   this one's, in {#reposition}.
+    class Notification < Tuile::Component::Overlay
       MAX_MESSAGES: Integer
       MAX_ROWS_PER_MESSAGE: Integer
       DISPLAY_SECONDS: Float
@@ -5891,16 +6232,6 @@ module Tuile
 
       def initialize: () -> void
 
-      # Load-bearing, not cosmetic: focus landing inside a non-modal popup sits
-      # outside the key-dispatch scope, where {ScreenPane#handle_key} delivers to
-      # nobody — every keystroke would go dead until the user pressed Tab.
-      # 
-      # _@return_ — false.
-      def focusable?: () -> bool
-
-      # _@return_ — false — see {#focusable?}.
-      def tab_stop?: () -> bool
-
       # Appends a message, dropping it (with a {Tuile.logger} warning) once
       # {MAX_MESSAGES} are held. Public so a caller holding the instance can
       # append without repeating {show}'s lookup.
@@ -5912,7 +6243,7 @@ module Tuile
 
       # Recomputes the box from its messages and re-anchors it to the screen's
       # top-right corner — so a SIGWINCH re-wraps and re-anchors, where
-      # {Popup#reposition} would have kept the stale left column of a *derived*
+      # {Overlay#reposition} would have kept the stale left column of a *derived*
       # position (off-screen entirely if the terminal narrowed).
       # 
       # Rebuilds the {TextView}'s text too, and every mutation routes through
@@ -5921,19 +6252,13 @@ module Tuile
       # from the width.
       def reposition: () -> void
 
-      # A notification is sized by its messages, so this always raises. Failing
-      # loudly beats accepting a size the next {#reposition} would discard.
-      # 
-      # _@param_ `_new_size`
-      def size=: ((Size | Fraction) _new_size) -> void
-
       # A left click dismisses the whole box, every message with it. Other buttons
       # are consumed and inert — including the scroll wheel, which would otherwise
       # nuke the box on a stray spin.
       # 
       # Deliberately *replaces* rather than augments: neither `super` nor
       # {HasContent#handle_mouse} may run, since both end at a
-      # `screen.focused = …` inside this subtree (see {#focusable?}).
+      # `screen.focused = …` inside this subtree (see {Overlay#focusable?}).
       # 
       # _@param_ `event`
       def handle_mouse: (MouseEvent event) -> void
@@ -6034,7 +6359,7 @@ module Tuile
     # The `█`/`░` pair is the same one {VerticalScrollBar} uses — East-Asian
     # Ambiguous and Neutral respectively, so under an ambiguous-as-wide terminal
     # the rendered length would vary with the fill level. Shipped anyway, per
-    # `DECISIONS.md` `D-ambiguous-width`: a bar that rhymes with the scrollbar
+    # `DECISIONS.md` `D_ambiguous_width`: a bar that rhymes with the scrollbar
     # beats a third convention, and if that bet is ever reversed both swap
     # together.
     class ProgressBar < Component
@@ -6240,12 +6565,9 @@ module Tuile
       # a read-only display field could override back to `false`. Only
       # `focusable?` lives here — `tab_stop?` diverges between leaf fields and
       # composing wrappers, so it stays per-class (`DECISIONS.md`
-      # `D-integer-field`).
+      # `D_integer_field`).
       def focusable?: () -> bool
 
-      # _@param_ `event`
-      def handle_mouse: (MouseEvent event) -> void
-
       # _@param_ `rect`
       def rect=: (Rect rect) -> void
 
@@ -6254,7 +6576,7 @@ module Tuile
 
     # A borderless, tinted, non-focusable floating selection list — the dropdown
     # a *driver* drops open, drives by forwarding movement keys, and commits a
-    # pick from: a non-modal {Popup} wrapping a {List} that never takes focus, so
+    # pick from: an {Overlay} wrapping a {List} that never takes focus, so
     # focus stays on the driver while the caller refills the rows, moves the
     # highlight, and reads the pick.
     # 
@@ -6284,7 +6606,7 @@ module Tuile
     # different tint (a `Theme.ref(:token)` keeps the flip-tracking).
     # 
     # UI-thread-confined, like every component (see {Screen}).
-    class ListDropdown < Tuile::Component::Popup
+    class ListDropdown < Tuile::Component::Overlay
       MOVE_KEYS: ::Array[String]
       MAX_VISIBLE_ROWS: Integer
 
@@ -6331,7 +6653,15 @@ module Tuile
       # Vertical flips but horizontal slides because covering the driver would
       # hide what is being chosen, while sharing its columns is the point.
       # 
-      # _@param_ `anchor` — the driver's rect; the dropdown never covers it.
+      # **`anchor` is the region actually occupied, and may be taller than one
+      # row** — "beneath" means the row *after* it, so a multi-row driver (a
+      # {Component::TextArea} carrying an autocomplete menu) is cleared entirely
+      # rather than overdrawn from its second row down. A widget that paints one
+      # row but may be *assigned* more height passes its face, not its rect:
+      # {ComboBox} and {Select} both do, since a {Window} content slot hands them
+      # the full inner height.
+      # 
+      # _@param_ `anchor` — the region the driver occupies, of any height; the dropdown never covers it.
       # 
       # _@param_ `rows` — how many rows there are to show — the content count, not the height: more than fits turns the scrollbar on. `0` collapses the dropdown to an empty rect (drivers close instead).
       # 
@@ -6366,7 +6696,7 @@ module Tuile
       # 
       # _@param_ `rows` — how many rows there are to show — the content count, not the height; more than fits turns the scrollbar on. `0` collapses the dropdown to an empty rect (drivers close instead).
       # 
-      # _@param_ `width` — the panel's width in columns, clamped to the screen. **Required, with no default:** `anchor.width` is the *parent's* width and would be meaningless here, so the caller measures (see `DECISIONS.md` `D-select` on why the width policy stays with the driver).
+      # _@param_ `width` — the panel's width in columns, clamped to the screen. **Required, with no default:** `anchor.width` is the *parent's* width and would be meaningless here, so the caller measures (see `DECISIONS.md` `D_select` on why the width policy stays with the driver).
       # 
       # _@param_ `max_rows` — rows shown before the list scrolls.
       def anchor_beside: (
@@ -6419,6 +6749,54 @@ module Tuile
       end
     end
 
+    # A {TextView} purpose-built for log output: auto-scroll is on, the
+    # scrollbar is visible, and lines arrive via {#log} — from any thread.
+    # Point a logger at a {LogTextView::IO} to route its lines here:
+    # 
+    #   view = Tuile::Component::LogTextView.new
+    #   logger = Logger.new(Tuile::Component::LogTextView::IO.new(view))
+    #   logger.info("started")   # appears in the view, from any thread
+    # 
+    # Any logger that writes formatted lines to an IO works the same way —
+    # for example `TTY::Logger` configured with the `:console` handler and
+    # `output: LogTextView::IO.new(view)`.
+    # 
+    # Add it to a layout as-is for a frameless log pane, or use {LogWindow}
+    # for the framed assembly. A {TextView} rather than a {List}: long lines
+    # (stacktraces, wide log records) word-wrap rather than ellipsize — a
+    # truncated log line hides the very detail you opened the log to read.
+    class LogTextView < Tuile::Component::TextView
+      def initialize: () -> void
+
+      # Appends the given line to the log. Safe to call from any thread —
+      # the one exception to the UI-thread confinement every component
+      # carries: the append is marshalled through `event_queue.submit`, so
+      # it lands once a loop drains the queue (deferred before the first
+      # loop; silently dropped after the loop has returned).
+      # 
+      # _@param_ `string` — the line (or multiple lines) to log; `nil` is a no-op.
+      def log: (String? string) -> void
+
+      # IO-shaped adapter that forwards each log line to its sink's `#log`.
+      # Implements both {#write} (stdlib `Logger`) and {#puts} (loggers that
+      # call `output.puts`, e.g. `TTY::Logger`).
+      class IO
+        # _@param_ `sink` — anything responding to `#log`.
+        def initialize: ((LogTextView | LogWindow) sink) -> void
+
+        # _@param_ `string`
+        def write: (String string) -> void
+
+        # _@param_ `string`
+        def puts: (String string) -> void
+
+        # Stdlib `Logger` only treats an object as an IO target when it
+        # responds to both {#write} and {#close}; otherwise it tries to
+        # interpret it as a filename. This is a no-op.
+        def close: () -> void
+      end
+    end
+
     # A {Window} that lists options identified by single keyboard keys, asks
     # the user to pick one, and fires a callback with the picked key.
     # 
@@ -6609,12 +6987,9 @@ module Tuile
       # a read-only display field could override back to `false`. Only
       # `focusable?` lives here — `tab_stop?` diverges between leaf fields and
       # composing wrappers, so it stays per-class (`DECISIONS.md`
-      # `D-integer-field`).
+      # `D_integer_field`).
       def focusable?: () -> bool
 
-      # _@param_ `event`
-      def handle_mouse: (MouseEvent event) -> void
-
       # _@param_ `rect`
       def rect=: (Rect rect) -> void
 
@@ -6625,6 +7000,254 @@ module Tuile
       attr_accessor item_label: (Proc | Method)
     end
 
+    # The confirm dialog: a {Window} asking a question — a caption, a prose
+    # {#message}, a centered row of buttons — plus the one-button degenerate
+    # case, the alert. Three factories cover the common shapes and open the
+    # dialog as a centered, content-sized {Popup}:
+    # 
+    #   Component::ConfirmWindow.alert("Export failed", "Contact support@example.com.")
+    #   Component::ConfirmWindow.confirm("Delete Report Q4?", "This cannot be undone.",
+    #                                    confirm: "Delete") { delete! }
+    #   Component::ConfirmWindow.yes_no("Overwrite file?", "target.txt already exists.") { overwrite! }
+    # 
+    # The component itself is the builder — declare any button set through
+    # {#button}, then {#open}:
+    # 
+    #   dialog = Component::ConfirmWindow.new("Unsaved changes")
+    #   dialog.message = "Save your changes before leaving?"
+    #   dialog.button("Save")    { save! }
+    #   dialog.button("Discard") { discard! }
+    #   dialog.button("Cancel")             # no action: pressing it dismisses
+    #   dialog.on_dismiss = -> { stay_put }
+    #   dialog.open
+    # 
+    # **Every button closes the dialog.** A button with a block then fires it; a
+    # button without one is a Cancel. ESC, `q`, an outside click and a Cancel
+    # button are all one outcome — {#on_dismiss}, fired exactly once, and only
+    # when no action button was chosen. There is deliberately no keep-open knob:
+    # a dialog that leads somewhere opens the next window from its callback.
+    # 
+    # Keys: Left/Right (and Tab) move between the buttons, Enter/Space press the
+    # focused one, and each button answers to its underlined mnemonic letter
+    # (see {#button}). The message scrolls without taking focus —
+    # {BODY_SCROLL_KEYS} are handed to it from anywhere in the dialog. Focus
+    # opens on the first button; Shift+Tab reaches the message, a tab stop of
+    # its own.
+    # 
+    # The popup sizes itself from what the dialog owns — caption, message,
+    # buttons — capped at half the screen ({#measured_size}), re-measured when
+    # any of them changes. Usable tiled too (add it to a {Layout}): buttons then
+    # fire their callbacks with nothing to close.
+    # 
+    # There is deliberately no content slot: the body is prose ({#message=}
+    # takes a component for the rare rich body, but the dialog then cannot
+    # measure it). A dialog collecting *input* is not a confirm dialog — build a
+    # `Popup.new(content: your_layout)`. See `DECISIONS.md` `D_confirm_window`
+    # for the API rationale.
+    class ConfirmWindow < Tuile::Component::Window
+      BODY_SCROLL_KEYS: ::Array[String]
+      RESERVED_MNEMONICS: ::Array[String]
+      HEIGHT_CHROME: Integer
+      WIDTH_CHROME: Integer
+
+      # _@param_ `caption` — the border title, coerced the same way {HasCaption#caption=} coerces it.
+      def initialize: (?(String | StyledString)? caption) -> void
+
+      # Also re-measures the popup: the caption participates in the width.
+      # 
+      # _@param_ `new_caption`
+      def caption=: ((String | StyledString)? new_caption) -> void
+
+      # Appends a button and returns it. A button with a block is an action
+      # button: pressing it closes the dialog, then fires the block. A button
+      # without one is a Cancel: pressing it closes the dialog, then fires
+      # {#on_dismiss}.
+      # 
+      #   dialog.button("Delete") { delete! }        # mnemonic d, underlined
+      #   dialog.button("Keep", mnemonic: "e")       # explicit letter
+      #   dialog.button("Cancel", mnemonic: nil)     # no mnemonic
+      # 
+      # The mnemonic — a printable letter activating the button from anywhere in
+      # the dialog, case-insensitively — is underlined in the caption. Any case
+      # is accepted, and the underline prefers the exact case given, so the case
+      # picks which occurrence is cued (`"Save As"` with `"A"` underlines the
+      # *As*), exactly as on {MenuBar#add_item}. The default `:auto` derives the
+      # caption's first letter (cueing it as displayed) and is best-effort:
+      # silently skipped when that letter is reserved, taken, or unusable. An
+      # explicit letter is a promise and raises when it cannot be kept.
+      # 
+      # Declare buttons before {#open}: adding one to an open dialog re-measures
+      # the popup, but momentarily bounces focus off the button row.
+      # 
+      # _@param_ `caption` — the button label.
+      # 
+      # _@param_ `mnemonic` — `:auto` (default), a printable one-column character, or `nil` for none.
+      # 
+      # _@return_ — the appended button.
+      def button: ((String | StyledString) caption, ?mnemonic: (Symbol | String)?) -> Button
+
+      # Opens the dialog as a centered modal {Popup} sized by {#measured_size}
+      # and returns that popup. ESC, `q` and an outside click dismiss it
+      # (firing {#on_dismiss}); every button closes it too.
+      # 
+      # _@return_ — the mounted popup; `popup.close` closes programmatically,
+      # as {#close} also does.
+      def open: () -> Popup
+
+      # Closes the popup {#open} mounted, which counts as a dismissal
+      # ({#on_dismiss} fires). No-op when not open, or when used tiled.
+      def close: () -> void
+
+      # The popup box this dialog wants: wide enough for the caption, the widest
+      # message line and the button row, tall enough for the wrapped message
+      # plus the button row — each capped at half of `reference`. The re-grow
+      # rule's caller-side measure query: the dialog measures only content it
+      # *owns*, so a {Component} assigned to {#message=} yields the full
+      # half-screen box.
+      # 
+      # _@param_ `reference` — the screen size to cap against.
+      def measured_size: (?Size reference) -> Size
+
+      # Focus lands on the first button rather than cascading into the message
+      # body, which sits before the button row in the tree.
+      def on_focus: () -> void
+
+      # Handles the dialog-wide keys: Left/Right move between the buttons,
+      # {BODY_SCROLL_KEYS} are hand-fed to the message body, and a mnemonic
+      # letter presses its button. Reached by bubbling — the focused button or
+      # body sees the key first, so a focused body consumes its own scroll keys
+      # before this runs.
+      # 
+      # _@param_ `key`
+      # 
+      # _@return_ — true if the key was handled.
+      def handle_key: (String key) -> bool
+
+      # Opens an acknowledgement dialog: a message and one button, whose press
+      # is the dismissal. The button exists for discoverability — ESC and `q`
+      # close too, but Tuile advertises no keys anywhere, and the button is
+      # clickable.
+      # 
+      # _@param_ `caption` — the border title.
+      # 
+      # _@param_ `message` — see {#message=}.
+      # 
+      # _@param_ `button` — the button label.
+      # 
+      # _@return_ — the mounted popup.
+      def self.alert: ((String | StyledString)? caption, (String | StyledString | Component)? message, ?button: (String | StyledString)) -> Popup
+
+      # Opens a two-button question: the block is the action, the cancel button
+      # (with ESC, `q` and an outside click) is the dismissal.
+      # 
+      #   Component::ConfirmWindow.confirm("Delete Report Q4?", "This cannot be undone.",
+      #                                    confirm: "Delete") { delete! }
+      # 
+      # _@param_ `caption` — the border title.
+      # 
+      # _@param_ `message` — see {#message=}.
+      # 
+      # _@param_ `confirm` — the action button's label.
+      # 
+      # _@param_ `cancel` — the dismissal button's label.
+      # 
+      # _@param_ `on_dismiss` — see {#on_dismiss}.
+      # 
+      # _@return_ — the mounted popup.
+      def self.confirm: (
+                          (String | StyledString)? caption,
+                          (String | StyledString | Component)? message,
+                          ?confirm: (String | StyledString),
+                          ?cancel: (String | StyledString),
+                          ?on_dismiss: Proc?
+                        ) -> Popup
+
+      # {.confirm} with Yes/No labels — the other canonical phrasing.
+      # 
+      # _@param_ `caption` — the border title.
+      # 
+      # _@param_ `message` — see {#message=}.
+      # 
+      # _@param_ `on_dismiss` — see {#on_dismiss}.
+      # 
+      # _@return_ — the mounted popup.
+      def self.yes_no: ((String | StyledString)? caption, (String | StyledString | Component)? message, ?on_dismiss: Proc?) -> Popup
+
+      # The chosen-button path, in the settled order: mark chosen, close the
+      # popup (whose on_close then skips the dismissal), fire the callback last
+      # so it sees the dialog already gone — a callback opening a follow-up
+      # popup gets clean focus-repair state.
+      # 
+      # _@param_ `btn`
+      def activate: (Button btn) -> void
+
+      # The popup's on_close: fires {#on_dismiss} unless a button was chosen —
+      # which makes ESC, `q`, an outside click, {#close}, a direct
+      # {Screen#remove_popup} and teardown all one event, fired exactly once.
+      def notice_dismissed: () -> void
+
+      # _@param_ `delta` — -1 or 1.
+      # 
+      # _@return_ — false when focus is not on a button (the key bubbles on).
+      def focus_button_step: (Integer delta) -> bool
+
+      # Validates an explicit mnemonic (raising, as {MenuBar#add_item} does —
+      # none of these has a sane answer at keypress time) or best-effort derives
+      # one from the caption's first letter (returning nil where the explicit
+      # path would raise).
+      # 
+      # _@param_ `caption`
+      # 
+      # _@param_ `mnemonic`
+      # 
+      # _@return_ — the downcased letter, or nil for none.
+      def resolve_mnemonic: (StyledString caption, (Symbol | String)? mnemonic) -> String?
+
+      # _@param_ `caption`
+      def derive_mnemonic: (StyledString caption) -> String?
+
+      # {StyledString#slice} counts **columns** while a caption search yields a
+      # **character** index, so the prefix is measured, never counted (the
+      # {MenuBar::Item} cue, duplicated per `D_float_field`'s shallow-shell rule).
+      # 
+      # _@param_ `caption`
+      # 
+      # _@param_ `cue` — the letter in the case it was given in — exact case first, so the case picks which occurrence is underlined.
+      def underline_mnemonic: (StyledString caption, String cue) -> StyledString
+
+      # Re-declares the button row's cross extent — the buttons' summed natural
+      # width — so the {Layout::Vertical} centers it. Remove-and-re-add is the
+      # only way to change a {Layout::Box} constraint; the row stays after the
+      # body because both `add`s append.
+      def recenter_button_row: () -> void
+
+      # _@return_ — columns of the button row at its natural width.
+      def button_row_width: () -> Integer
+
+      # Re-measures the popup while open; a no-op tiled or before {#open}.
+      def resize_popup: () -> void
+
+      # Callback taking no arguments, fired when the dialog is dismissed — ESC,
+      # `q`, an outside click, or a {#button} declared without a block. Fires
+      # exactly once per {#open}, and never when an action button was chosen.
+      attr_accessor on_dismiss: Proc?
+
+      # _@return_ — whatever {#message=} was
+      # given — set a `String`, read that `String` back. The component
+      # rendering it is derived, never returned.
+      attr_accessor message: (String | StyledString | Component)?
+
+      # The {Popup} that {#open} wraps the dialog in: its declared size is
+      # derived from the dialog on every {#reposition}, so a message change and
+      # a SIGWINCH both re-measure against the current screen.
+      class MeasuredPopup < Tuile::Component::Popup
+        # _@param_ `window`
+        def initialize: (ConfirmWindow window) -> void
+
+        def reposition: () -> void
+      end
+    end
+
     # A {TextField} that paints one mask glyph per character instead of the
     # text. Editing, caret, clicks and horizontal scrolling are the field's,
     # unchanged:
@@ -6799,12 +7422,9 @@ module Tuile
       # a read-only display field could override back to `false`. Only
       # `focusable?` lives here — `tab_stop?` diverges between leaf fields and
       # composing wrappers, so it stays per-class (`DECISIONS.md`
-      # `D-integer-field`).
+      # `D_integer_field`).
       def focusable?: () -> bool
 
-      # _@param_ `event`
-      def handle_mouse: (MouseEvent event) -> void
-
       # _@param_ `rect`
       def rect=: (Rect rect) -> void
 
@@ -7013,7 +7633,7 @@ module Tuile
       # a read-only display field could override back to `false`. Only
       # `focusable?` lives here — `tab_stop?` diverges between leaf fields and
       # composing wrappers, so it stays per-class (`DECISIONS.md`
-      # `D-integer-field`).
+      # `D_integer_field`).
       def focusable?: () -> bool
 
       # _@return_ — current text contents.
@@ -7121,6 +7741,48 @@ module Tuile
     attr_reader light: Theme
   end
 
+  # How many colors the terminal on the other end can actually show — the
+  # depth {Color#quantize} degrades a color to:
+  # 
+  #   ColorDepth.detect                                        # => :truecolor
+  #   ColorDepth.detect(env: { "TERM" => "xterm-256color" })   # => :palette256
+  #   ColorDepth.detect(env: {})                               # => :ansi16
+  # 
+  # Env-only: no terminal round-trip, so unlike {TerminalBackground.detect}
+  # there is no stdin timing to respect, and the answer cannot go stale
+  # mid-session the way a background color can.
+  # 
+  # Terminals lie in both directions — `COLORTERM` frequently doesn't survive
+  # ssh (it isn't in the default `SendEnv` set) or tmux — so {OVERRIDE_ENV}
+  # beats every other signal, the escape hatch for a terminal detected wrong.
+  # Misdetection otherwise lands *conservatively*: a truecolor tmux
+  # advertising only `tmux-256color` reads as `:palette256`, which renders
+  # coarser but never mangled.
+  # 
+  # == Implementation details
+  # 
+  # Terminfo is deliberately not consulted — its `RGB` boolean and
+  # `colors#0x1000000` would mean shelling out to `tput`/`infocmp` at every
+  # startup, and the env ladder plus the override already covers the real
+  # terminal matrix.
+  module ColorDepth
+    DEPTHS: ::Array[Symbol]
+    OVERRIDE_ENV: String
+    TRUECOLOR_COLORTERM: ::Array[String]
+
+    # The terminal's color depth, from {OVERRIDE_ENV}, else `COLORTERM`,
+    # else `TERM` (a `-direct` entry means 24-bit, a `256color` one the
+    # palette), else the 16-color floor.
+    # 
+    # _@param_ `env` — environment to read; defaults to `ENV` (which duck-types the `[]` lookup).
+    # 
+    # _@return_ — one of {DEPTHS}.
+    def self.detect: (?env: ::Hash[String, String]) -> Symbol
+
+    # _@param_ `value` — the raw {OVERRIDE_ENV} value.
+    def self.parse_override: (String value) -> Symbol
+  end
+
   # An event queue. The idea is that all UI-related updates run from the thread
   # which runs the event queue only; this removes any need for locking and/or
   # need for thread-safety mechanisms.
@@ -7298,6 +7960,26 @@ module Tuile
       attr_reader scheme: Symbol
     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
+      # _@param_ `key` — key read via {Keys.getkey}.
+      # 
+      # _@return_ — nil when `key` is not an OSC 11
+      # background reply.
+      def self.parse: (String key) -> BackgroundColorEvent?
+
+      # _@return_ — the reported background, 24-bit RGB.
+      attr_reader color: Color
+    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.
@@ -7397,10 +8079,31 @@ module Tuile
 
     def invalidated_clear: () -> void
 
+    # 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`
+    def background_color=: (Color color) -> void
+
     # 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.
-    def detect_scheme: () -> Symbol
+    # 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=}.
+    def detect_background: () -> TerminalBackground::Result
+
+    # 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.
+    def detect_color_depth: () -> Symbol
 
     # _@return_ — whatever {#print} / {#emit} produced so far.
     # Component painting lands in {#buffer}, not here — assert on
@@ -7474,30 +8177,32 @@ module Tuile
   # The pane owns no chrome of its own — no status bar, no reserved row.
   # {#content} gets the full pane rect, and an app that wants a status line
   # builds one into its own layout and drives it from
-  # {Screen#on_focus_changed=} (`D-status-bar`).
+  # {Screen#on_focus_changed=} (`D_status_bar`).
   # 
   # The pane is not a {Component::Layout}: popups deliberately overlap content
   # (Z-ordered, full overdraw, no clipping) and key/mouse dispatch follows
   # modal-popup rules rather than active-child dispatch.
   class ScreenPane < Tuile::Component
+    FINAL_METHODS: ::Array[Symbol]
+
     def initialize: () -> void
 
     def focusable?: () -> bool
 
-    # Adds a popup and invalidates it for repaint. A modal popup is centered
-    # and grabs focus; a non-modal overlay ({Component::Popup#modal?} false) is
-    # 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.
+    # Adds an overlay and invalidates it for repaint. A {Component::Popup} is
+    # centered and grabs focus; a bare {Component::Overlay} is left wherever
+    # the caller positioned 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
+    # The *whole subtree* is invalidated, not just the overlay 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.
+    # without this the overlay's contents would stay blank on reopen.
     # 
-    # _@param_ `window`
-    def add_popup: (Component::Popup window) -> void
+    # _@param_ `window` — any overlay, modal or not.
+    def add_popup: (Component::Overlay window) -> void
 
     # Removes a popup. If the popup held focus, focus shifts to the now-topmost
     # remaining popup, falling back to the focus snapshotted when the popup
@@ -7522,11 +8227,11 @@ module Tuile
     # _@return_ — true if this pane currently hosts the popup.
     def has_popup?: (Component window) -> bool
 
-    # _@return_ — the topmost *modal* popup, or nil when
-    # only non-modal overlays (or no popups) are open. This is the "modal
+    # _@return_ — the topmost modal overlay, or nil when
+    # only bare {Component::Overlay}s (or none) are open. This is the "modal
     # owner": the popup that scopes key dispatch, blocks mouse clicks, and
-    # confines Tab cycling. Non-modal overlays are excluded — they float above
-    # the content without capturing input.
+    # confines Tab cycling. Bare overlays are excluded — they float above the
+    # content without capturing input.
     def modal_popup: () -> Component::Popup?
 
     # Re-lays out children whenever the pane's own rect changes.
@@ -7535,7 +8240,7 @@ module Tuile
     def rect=: (Rect new_rect) -> void
 
     # Gives {#content} the whole pane rect — the pane reserves nothing for
-    # itself. Each popup re-resolves its {Component::Popup#size} against the new
+    # itself. Each popup re-resolves its {Component::Popup#declared_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).
@@ -7582,12 +8287,12 @@ module Tuile
     # content beneath.
     # 
     # A left click also *dismisses* the open popups it landed outside of that
-    # asked for it ({Component::Popup#close_on_outside_click?}). That is a
+    # asked for it ({Component::Overlay#close_on_outside_click?}). That is a
     # second thing happening on a click, but not a second dispatch: the click is
     # still delivered exactly once, down one chain, and a dismissed popup is
     # closed rather than told.
     # 
-    # "Outside" is measured against the {Component::Popup#owner} chain, not
+    # "Outside" is measured against the {Component::Overlay#owner} chain, not
     # against one rect and not against stacking order: the popup the click hit
     # is kept, and so is every popup that one *belongs to*, transitively. That
     # is what stops a dialog being dismissed by a click on a dropdown its own
@@ -7628,21 +8333,22 @@ module Tuile
     # _@param_ `child`
     def on_child_removed: (Component child) -> void
 
-    # The popups a click counts as landing *inside*: the one it hit, plus every
-    # popup that one belongs to, up the {Component::Popup#owner} chain. An owner
-    # is any component, so it is resolved to the popup enclosing it (a popup
-    # resolves to itself) — which keeps the relationship a live tree question
-    # rather than one frozen when the overlay opened. The `include?` guard makes
-    # a mis-wired cycle terminate instead of hanging the UI thread.
+    # The overlays a click counts as landing *inside*: the one it hit, plus
+    # every overlay that one belongs to, up the {Component::Overlay#owner}
+    # chain. An owner is any component, so it is resolved to the overlay
+    # enclosing it (an overlay resolves to itself) — which keeps the
+    # relationship a live tree question rather than one frozen when the overlay
+    # opened. The `include?` guard makes a mis-wired cycle terminate instead of
+    # hanging the UI thread.
     # 
-    # _@param_ `hit` — the popup the click landed in, if any.
-    def kept_by: (Component::Popup? hit) -> ::Array[Component::Popup]
+    # _@param_ `hit` — the overlay the click landed in, if any.
+    def kept_by: (Component::Overlay? hit) -> ::Array[Component::Overlay]
 
     # _@param_ `component`
     # 
-    # _@return_ — `component` itself when it is a popup,
-    # else the nearest popup above it, else nil.
-    def enclosing_popup: (Component? component) -> Component::Popup?
+    # _@return_ — `component` itself when it is an
+    # overlay, else the nearest overlay above it, else nil.
+    def enclosing_popup: (Component? component) -> Component::Overlay?
 
     # Delivers `key` to {Screen#focused} and bubbles it up the ancestor chain,
     # stopping at (and including) `scope`. Delivers to no one — returning false
@@ -7675,15 +8381,16 @@ module Tuile
     # _@return_ — the tiled content component.
     attr_accessor content: Component?
 
-    # _@return_ — overlay popups in stacking order; last is
-    # topmost. Holds both modal popups and non-modal overlays
-    # ({Component::Popup#modal?}). The array must not be mutated by callers.
-    attr_reader popups: ::Array[Component]
+    # _@return_ — the open overlays in stacking order;
+    # last is topmost. Holds both {Component::Popup} modals and bare
+    # {Component::Overlay}s ({Component::Overlay#modal?}). The array must not
+    # be mutated by callers.
+    attr_reader popups: ::Array[Component::Overlay]
   end
 
   # 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
+  # `underline`, `strikethrough`, `inverse`). 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
@@ -7714,7 +8421,7 @@ module Tuile
   # ## Parser
   # 
   # {.parse} is strict by default — it recognizes only the SGR codes for
-  # {Style}'s attributes (fg/bg/bold/italic/underline/strikethrough) and
+  # {Style}'s attributes (fg/bg/bold/italic/underline/strikethrough/inverse) 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
@@ -7849,6 +8556,10 @@ module Tuile
     # so a log line keeps its red error-level bg while its plain text picks up an
     # inherited panel tint.
     # 
+    # An `inverse` span counts as backgrounded and is skipped even when its `bg`
+    # member is nil: SGR 7 swaps the pair in effect, so a bg filled under it
+    # would recolor the span's *glyphs*, not the ground behind them.
+    # 
     # _@param_ `bg` — background color, coerced via {Color.coerce}. `nil` returns `self` unchanged.
     def under_bg: ((Color | Symbol | Integer | ::Array[Integer])? bg) -> StyledString
 
@@ -7894,6 +8605,20 @@ module Tuile
     # _@param_ `underline` — whether the spans should be underlined.
     def with_underline: (?underline: bool) -> StyledString
 
+    # Returns a new {StyledString} with `inverse` applied to every span,
+    # preserving each span's text and other style attributes. Inverse swaps
+    # whatever fg/bg are actually in effect at each cell — terminal defaults
+    # included — so a focus chip built with it reads as "backgrounded" on any
+    # terminal palette without picking a single color:
+    # 
+    #   StyledString.plain(" 1 VMs ").with_inverse   # the inverted-chip idiom
+    # 
+    # There is deliberately no `under_inverse`, for the reason {#with_bold}
+    # spells out. Pass `inverse: false` to clear it.
+    # 
+    # _@param_ `inverse` — whether the spans should be inverted.
+    def with_inverse: (?inverse: bool) -> StyledString
+
     def inspect: () -> String
 
     def build_ansi: () -> String
@@ -7987,6 +8712,9 @@ module Tuile
     #   @return [Boolean]
     # @!attribute [r] strikethrough
     #   @return [Boolean]
+    # @!attribute [r] inverse
+    #   @return [Boolean] swap the fg/bg *in effect* at the cell (SGR 7) —
+    #     including terminal defaults, which `fg`/`bg` can't name.
     class Style
       DEFAULT: Style
 
@@ -8001,13 +8729,16 @@ module Tuile
       # _@param_ `underline`
       # 
       # _@param_ `strikethrough`
+      # 
+      # _@param_ `inverse`
       def self.new: (
                       ?fg: (Color | Symbol | Integer | ::Array[Integer])?,
                       ?bg: (Color | Symbol | Integer | ::Array[Integer])?,
                       ?bold: bool,
                       ?italic: bool,
                       ?underline: bool,
-                      ?strikethrough: bool
+                      ?strikethrough: bool,
+                      ?inverse: bool
                     ) -> Style
 
       def default?: () -> bool
@@ -8045,6 +8776,10 @@ module Tuile
       attr_reader underline: bool
 
       attr_reader strikethrough: bool
+
+      # _@return_ — swap the fg/bg *in effect* at the cell (SGR 7) —
+      # including terminal defaults, which `fg`/`bg` can't name.
+      attr_reader inverse: bool
     end
 
     # A maximal run of text sharing a single {Style}. `text` is plain — it
@@ -8203,8 +8938,9 @@ module Tuile
     end
   end
 
-  # Detects whether the terminal background is light or dark, so {Screen}
-  # can pick {Theme::LIGHT} or {Theme::DARK} automatically at startup.
+  # Detects the terminal's background color — both the light/dark scheme
+  # {Screen} picks {Theme::LIGHT} or {Theme::DARK} from, and, when the
+  # terminal answers the query, the actual RGB behind it.
   # 
   # Two mechanisms, in order of reliability:
   # 
@@ -8217,13 +8953,19 @@ module Tuile
   #    bounded by a short timeout.
   # 2. **`COLORFGBG` env var** — rxvt/konsole export `"fg;bg"` ANSI palette
   #    indices. Less reliable (stale across SSH/tmux, often unset); used
-  #    only when OSC 11 yields nothing.
+  #    only when OSC 11 yields nothing. Palette indices carry no RGB, so
+  #    this path fills in {Result#scheme} and leaves {Result#color} nil.
   # 
   # **Timing matters**: the OSC 11 reply arrives on stdin, so the query
   # must complete before {EventQueue#start_key_thread} owns stdin —
   # otherwise the reply bytes get consumed as garbage keystrokes. {Screen}
   # calls {.detect} from its constructor, which apps run before
   # {Screen#run_event_loop}; don't call this after the event loop started.
+  # 
+  # Once the loop *is* running the query is still available, from the other
+  # side: {Screen} writes {QUERY} on every OS appearance flip and the key
+  # thread — which owns stdin by then — reads the reply back through
+  # {Keys.getkey} and {.parse}. See {Screen#background_color}.
   module TerminalBackground
     QUERY_TIMEOUT: Float
     QUERY: String
@@ -8234,6 +8976,9 @@ module Tuile
     # Detects the terminal background. Queries OSC 11 when both `input`
     # and `output` are TTYs, falling back to `COLORFGBG`.
     # 
+    #   TerminalBackground.detect
+    #   # => #<data Result scheme=:dark, color=#<Tuile::Color [30, 30, 46]>>
+    # 
     # _@param_ `input` — where the OSC 11 reply arrives (the TTY input).
     # 
     # _@param_ `output` — where the query is written (the TTY output).
@@ -8242,25 +8987,41 @@ module Tuile
     # 
     # _@param_ `timeout` — max seconds to wait for the OSC 11 reply.
     # 
-    # _@return_ — `:light`, `:dark`, or nil when undetectable.
+    # _@return_ — nil when the background is undetectable —
+    # neither mechanism answered.
     def self.detect: (
                        ?input: IO,
                        ?output: IO,
                        ?env: ::Hash[String, String],
                        ?timeout: Numeric
-                     ) -> Symbol?
+                     ) -> Result?
+
+    # Parses an OSC 11 reply — the terminal's answer to {QUERY}, matched
+    # anywhere in `reply`.
+    # 
+    #   TerminalBackground.parse("\e]11;rgb:1e1e/1e1e/2e2e\a").color
+    #   # => #<Tuile::Color [30, 30, 46]>
+    # 
+    # Public because a reply also arrives *mid-session*, long after
+    # {.detect}'s own bounded read: once the key thread owns stdin, a
+    # whole reply surfaces as one "key" from {Keys.getkey}.
+    # 
+    # _@param_ `reply` — raw terminal output that may contain a reply.
+    # 
+    # _@return_ — nil when `reply` holds no OSC 11 reply.
+    def self.parse: (String reply) -> Result?
 
-    # Writes the OSC 11 query and classifies the reply. The whole
-    # exchange runs with `input` in raw mode: the reply has no trailing
-    # newline, so a canonical-mode read would block past the timeout,
-    # and echo would smear the reply bytes onto the screen.
+    # Writes the OSC 11 query and parses the reply. The whole exchange
+    # runs with `input` in raw mode: the reply has no trailing newline,
+    # so a canonical-mode read would block past the timeout, and echo
+    # would smear the reply bytes onto the screen.
     # 
     # _@param_ `input`
     # 
     # _@param_ `output`
     # 
     # _@param_ `timeout`
-    def self.query_osc11: (IO input, IO output, Numeric timeout) -> Symbol?
+    def self.query_osc11: (IO input, IO output, Numeric timeout) -> Result?
 
     # Accumulates reply bytes until a BEL/ST terminator or the deadline.
     # Terminals that don't support OSC 11 never reply — returning
@@ -8271,13 +9032,20 @@ module Tuile
     # _@param_ `timeout`
     def self.read_reply: (IO input, Numeric timeout) -> String
 
-    # Relative luminance of the reported background, scaled per
-    # component hex width (xterm replies 4 digits per channel, others 2).
+    # Light or dark, by relative luminance against a 0.5 threshold.
     # 
-    # _@param_ `components` — three hex strings.
+    # _@param_ `components` — red, green and blue, each 0.0..1.0.
     # 
     # _@return_ — `:light` or `:dark`.
-    def self.classify: (::Array[String] components) -> Symbol
+    def self.classify: (::Array[Float] components) -> Symbol
+
+    # The reported background as a 24-bit {Color}. Quantizing xterm's
+    # 16-bit-per-channel reply down to 8 loses nothing a terminal can
+    # display, and keeps the exposed value in the type the rest of Tuile
+    # paints with.
+    # 
+    # _@param_ `components` — red, green and blue, each 0.0..1.0.
+    def self.to_color: (::Array[Float] components) -> Color
 
     # `COLORFGBG` is `"fg;bg"` (rxvt sometimes `"fg;default;bg"`) with
     # ANSI palette indices. White-ish backgrounds — 7 (white) and the
@@ -8286,6 +9054,27 @@ module Tuile
     # 
     # _@param_ `value`
     def self.from_colorfgbg: (String? value) -> Symbol?
+
+    # What a detection found: the light/dark `scheme`, and the background
+    # `color` when a terminal actually reported one.
+    # 
+    # `color` is nil whenever the scheme came from the `COLORFGBG`
+    # fallback, so a consumer deriving a tint from the background must
+    # handle nil — plenty of terminals answer neither query.
+    # 
+    # @!attribute [r] scheme
+    #   @return [Symbol] `:light` or `:dark`.
+    # @!attribute [r] color
+    #   @return [Color, nil] the reported background as 24-bit RGB, or nil
+    #     when only `COLORFGBG` answered.
+    class Result < Data
+      # _@return_ — `:light` or `:dark`.
+      attr_reader scheme: Symbol
+
+      # _@return_ — the reported background as 24-bit RGB, or nil
+      # when only `COLORFGBG` answered.
+      attr_reader color: Color?
+    end
   end
 
   # A vertical scrollbar that computes which character to draw at each row.