tuile 0.12.0 → 0.14.0

data/sig/tuile.rbs

@@ -23,6 +23,7 @@ module Tuile
   # same form.
   module Ansi
     RESET: String
+    BEL: String
     SYNC_BEGIN: String
     SYNC_END: String
   end
@@ -78,6 +79,10 @@ module Tuile
     ENTER: String
     TAB: String
     SHIFT_TAB: String
+    BRACKETED_PASTE_ON: String
+    BRACKETED_PASTE_OFF: String
+    PASTE_START: String
+    PASTE_END: String
 
     # True iff `key` is a single printable character — a one-character string
     # whose codepoint is not in Unicode's C (Other) category. Rejects multi-
@@ -99,6 +104,43 @@ module Tuile
     # 
     # _@return_ — key, such as {DOWN_ARROW}.
     def self.getkey: () -> String
+
+    # Reads the body of a bracketed paste, having just read {PASTE_START}, and
+    # returns it {.normalize_paste}d:
+    # 
+    #   Keys.getkey                    # => "\e[200~"
+    #   Keys.read_paste                # => "one\ntwo"   (terminator consumed)
+    # 
+    # Reads **raw**, one byte at a time, rather than looping on {.getkey}: a
+    # pasted `\e` would send `getkey` gulping five bytes of the *payload* as an
+    # escape tail, surfacing them as phantom keypresses. One byte at a time is
+    # also what keeps the terminator from being over-read — nothing past
+    # {PASTE_END} is consumed, so typing that lands behind a paste survives.
+    # 
+    # Blocks until the terminator arrives; returns what it has at EOF.
+    # 
+    # _@return_ — the pasted text, UTF-8, without the brackets.
+    def self.read_paste: () -> String
+
+    # Rewrites a raw paste payload into the one convention callers see: `\n`
+    # line endings, valid UTF-8.
+    # 
+    #   Keys.normalize_paste("a\r\nb\rc")   # => "a\nb\nc"
+    # 
+    # Both are terminal-layer artifacts, not text: a terminal with bracketed
+    # paste *off* rewrites the clipboard's `\n` to `\r` so a paste looks like
+    # typing, and several keep doing it inside the brackets — so the byte a
+    # line break arrives as is not something a component should have to know.
+    # Invalid bytes are scrubbed to `U+FFFD`, which is what lets
+    # {Component#handle_paste} take any clipboard, a binary file included,
+    # without the grapheme-cluster walk raising downstream.
+    # 
+    # Control characters other than `\n` are left alone: they are content, and
+    # what a *text buffer* may hold is {Component::AbstractStringField}'s call,
+    # not this layer's.
+    # 
+    # _@param_ `text` — raw payload.
+    def self.normalize_paste: (String text) -> String
   end
 
   # A rectangle, with integer `left`, `top`, `width` and `height`, all 0-based.
@@ -232,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
@@ -280,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.
@@ -294,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])
@@ -593,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
@@ -754,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
@@ -818,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
@@ -879,10 +1007,15 @@ module Tuile
   # Everything on screen hangs off {#pane} (a {ScreenPane}): the tiled
   # {#content} (set via {#content=}, filling the whole terminal and laying
   # out its own children), the modal/overlay {#popups} stack (opened via
-  # {Component::Popup#open}, drawn on top of the content), and the bottom
-  # status bar. Popups are *not* sized from their content — each carries its
-  # own top-down {Component::Popup#size} — and they deliberately overdraw the
-  # content without clipping.
+  # {Component::Popup#open}, drawn on top of the content). Popups are *not*
+  # sized from their content — each carries its own top-down
+  # {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`).
   # 
   # ## Repaint model
   # 
@@ -929,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
@@ -957,27 +1091,11 @@ module Tuile
     # _@param_ `component`
     def invalidate: (Component component) -> void
 
-    # Rebuild the status-bar text from the current focus and global-shortcut
-    # registry. Called from {#focused=} and whenever the global registry
-    # changes. Popups own their own "q Close" prefix in `#keyboard_hint`;
-    # for the tiled case Screen tacks on the global "q quit" instead.
-    # Global-shortcut hints get spliced in too — see {#global_shortcut_hints}
-    # for the over_popups filter rule.
-    def refresh_status_bar: () -> void
-
-    # Status-bar hints from currently-registered global shortcuts.
-    # When a popup is open, only `over_popups: true` shortcuts contribute —
-    # the rest don't fire in that context, so showing them would be a lie.
-    # Insertion order is preserved (Hash iteration order).
-    # 
-    # _@param_ `popup_open`
-    def global_shortcut_hints: (popup_open: bool) -> ::Array[String]
-
-    # 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} /
@@ -988,7 +1106,9 @@ module Tuile
     # ownership reverts to the creating thread once it returns.
     # 
     # _@param_ `capture_mouse` — when true (default), enables xterm mouse tracking so clicks and scroll wheel arrive as {MouseEvent}s and feed {Component#handle_mouse}. When false, no tracking escape sequence is written: the terminal keeps its native click handling, which is what you want if the app benefits more from select-to-copy than from click-to-focus. Components' `handle_mouse` is simply never invoked from the loop in that mode (the terminal stops sending the bytes).
-    def run_event_loop: (?capture_mouse: bool) -> void
+    # 
+    # _@param_ `bracketed_paste` — when true (default), enables DEC private mode 2004 so pasted text arrives whole, as {Component#handle_paste}, instead of as one keystroke per character — which is the only way a pasted line break can be told from a typed Enter. When false, a paste streams in as keys again and a component that gives ENTER a meaning fires it once per pasted line. Turn it off only for a terminal that mishandles the mode.
+    def run_event_loop: (?capture_mouse: bool, ?bracketed_paste: bool) -> void
 
     # Advances focus to the next {Component#tab_stop?} in tree order, wrapping
     # around. Scope is the topmost popup if one is open, otherwise {#content}
@@ -1021,18 +1141,14 @@ module Tuile
     # - **{EDITING_KEYS}** — `ENTER`, `BACKSPACE`, `DELETE` and the arrows,
     #   which every editable widget needs.
     # 
-    #   screen.register_global_shortcut(Keys::CTRL_L,
-    #                                   over_popups: true,
-    #                                   hint: "^L #{screen.theme.hint("log")}") do
+    #   screen.register_global_shortcut(Keys::CTRL_L, over_popups: true) do
     #     log_popup.open
     #   end
     # 
     # _@param_ `key` — unprintable key (e.g. {Keys::CTRL_L}, {Keys::ESC}).
     # 
     # _@param_ `over_popups` — when true, fires even while a modal popup is open (pre-empting the popup); when false (default), suppressed while any popup is open so the popup gets the key.
-    # 
-    # _@param_ `hint` — preformatted status-bar hint; nil (default) is silent. Colors are baked in — re-register after a {#theme=} to recolor.
-    def register_global_shortcut: (String key, ?over_popups: bool, ?hint: String?) -> void
+    def register_global_shortcut: (String key, ?over_popups: bool) -> void
 
     # Removes a shortcut previously installed by {#register_global_shortcut}.
     # No-op if `key` was not registered.
@@ -1040,16 +1156,13 @@ module Tuile
     # _@param_ `key`
     def unregister_global_shortcut: (String key) -> void
 
-    # _@return_ — current active tiled component.
-    def active_window: () -> Component?
-
-    # 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
@@ -1060,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}
@@ -1081,15 +1194,35 @@ 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
 
+    # Rings the terminal bell ({Ansi::BEL}) — the signal for a keystroke that
+    # went nowhere, e.g. a letter matching no menu mnemonic while a menu is
+    # open.
+    # 
+    #   return true if activate_mnemonic(key)
+    # 
+    #   screen.beep   # no match: the key is swallowed, say so
+    #   true
+    # 
+    # Writes **immediately** rather than riding the next frame: a beep is not
+    # part of a frame, and the keystrokes worth beeping at are precisely the
+    # ones that invalidate nothing, so {#repaint} may never emit at all. Whether
+    # the user hears anything is the terminal's setting to make, so there is no
+    # Tuile-level enable/disable knob.
+    def beep: () -> void
+
     # Repaints the screen; tries to be as effective as possible, by only
     # considering invalidated components and flushing just the changed cells
     # of {#buffer}. Called once per event-loop tick (on {EventQueue::EmptyQueueEvent});
@@ -1103,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
@@ -1173,6 +1324,19 @@ module Tuile
     # _@param_ `event`
     def handle_mouse: (MouseEvent event) -> void
 
+    # Delivers pasted text down the focus chain ({ScreenPane#handle_paste}).
+    # 
+    # Deliberately *not* the key ladder: a paste is not a keystroke, so it
+    # skips Tab traversal and the global-shortcut registry entirely and goes
+    # straight to delivery. Unhandled text is dropped — there is no fallback
+    # that replays it as keys, which would put back the very ambiguity mode
+    # 2004 exists to remove.
+    # 
+    # _@param_ `text`
+    # 
+    # _@return_ — true if some component consumed it.
+    def handle_paste: (String text) -> bool
+
     def event_loop: () -> void
 
     # _@return_ — the structural root of the component tree.
@@ -1181,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
@@ -1225,14 +1399,58 @@ 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
 
     # _@return_ — currently focused component.
     attr_accessor focused: Component?
 
-    # Entry in the global shortcut registry: the block to run, whether it
-    # pre-empts open popups, and an optional preformatted status-bar hint.
+    # Called after the focused component *changes* — including to and from
+    # `nil`, and including the focus repair that runs when a popup closes.
+    # Takes no arguments; read {#focused} (and walk its `parent` chain) for the
+    # new state.
+    # 
+    # 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`).
+    # 
+    #   screen.on_focus_changed = -> { bar.text = hint_for(screen.focused) }
+    # 
+    # **Edge-triggered**, like {Component#on_attached}: re-assigning the
+    # component that already has focus fires nothing, so a callback can be as
+    # expensive as rebuilding a hint string without a `did it really change?`
+    # guard of its own. That matters more than it looks — `ScreenPane#content=`
+    # clears focus on every content swap, which on a level-triggered hook would
+    # fire a nil→nil notification during assembly.
+    # 
+    # It runs *after* the active-flag cascade and `on_focus`, so the tree is
+    # settled. Two things a callback must tolerate: {#focused} being `nil`, and
+    # firing during {#close} — teardown clears focus, exactly as it fires
+    # {Component#on_detached}. A raising callback propagates out of {#focused=}
+    # and leaves focus assigned; keep it trivial, as with the attach hooks.
+    attr_accessor on_focus_changed: Proc?
+
+    # Entry in the global shortcut registry: the block to run, and whether it
+    # pre-empts open popups.
     # @api private
     class Shortcut < Data
       # Returns the value of attribute block
@@ -1240,9 +1458,6 @@ module Tuile
 
       # Returns the value of attribute over_popups
       attr_reader over_popups: Object
-
-      # Returns the value of attribute hint
-      attr_reader hint: Object
     end
   end
 
@@ -1285,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
 
@@ -1301,14 +1576,29 @@ module Tuile
     def effective_bg_color: () -> Color?
 
     # Repaints the component. The default does the bookkeeping most components
-    # need: it clears the background, and for a container whose children leave
-    # gaps in {#rect} it re-invalidates those children so they repaint over the
-    # cleared area (what makes mixed-width form layouts safe). A container whose
-    # children fully tile {#rect} is left alone — the children cover everything.
+    # need: it clears the background — unless the direct children already tile
+    # {#rect}, in which case there is no gap to wipe and blanking cells they are
+    # about to repaint would only make them dirty — and then re-invalidates
+    # those children so they paint over the cleared area. That is what makes
+    # mixed-width form layouts safe.
     # 
     # Call `super` from your own `repaint` to inherit this. Skip it only if you
     # 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
+    # ancestor's `clear_background` wipes the whole ancestor rect — siblings and
+    # grandchildren included — and re-invalidates only its *direct* children, so
+    # the notice has to keep travelling down or the cleared cells are never
+    # repainted. Cheap by construction: repainting the same glyphs leaves
+    # {Buffer::Cell} unchanged, so nothing extra reaches the wire.
     def repaint: () -> void
 
     # Called when a key is pressed; override to act on keys you care about (the
@@ -1322,8 +1612,35 @@ module Tuile
     # _@return_ — true if the key was handled, false if not.
     def handle_key: (String _key) -> bool
 
-    # Handles mouse event. Default implementation focuses this component when
-    # clicked (if {#focusable?}).
+    # Called when text is pasted while this component is on the focus chain;
+    # override to accept it (the default reports every paste unhandled, and
+    # unhandled text is dropped). Arrives whole and `\n`-normalized, so
+    # `text.lines.size` is the paste's line count and a single mutation can
+    # absorb it:
+    # 
+    #   def handle_paste(text)
+    #     self.caption = "[Pasted #{text.lines.size} lines]"
+    #     true
+    #   end
+    # 
+    # Reaching here means the terminal said "this came from the clipboard" —
+    # {Component::AbstractStringField} inserts it at the caret, which is why a
+    # subclass that rebinds ENTER to submit needs no paste handling of its own
+    # to stop firing once per pasted line.
+    # 
+    # _@param_ `_text` — the pasted text.
+    # 
+    # _@return_ — true if the paste was consumed.
+    def handle_paste: (String _text) -> bool
+
+    # 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
@@ -1399,15 +1716,10 @@ module Tuile
     # _@return_ — absolute screen coordinates, or nil to hide.
     def cursor_position: () -> Point?
 
-    # _@return_ — formatted keyboard hint surfaced in the status bar by
-    # {Screen} when this component is the active tiled window or the
-    # topmost popup. Empty by default; override to advertise shortcuts.
-    def keyboard_hint: () -> String
-
     # Adopts `child`: places it in {#children} and wires its parent pointer.
     # 
-    #   add_child(@status_bar)                              # paints last
-    #   add_child(popup, at: @children.index(@status_bar))  # …just before it
+    #   add_child(content, at: 0)   # the tiled layer, painted beneath …
+    #   add_child(@footer)          # … and chrome appended, painted over it
     # 
     # _@param_ `child` — must not already have a parent.
     # 
@@ -1506,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).
     # 
@@ -1584,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.
@@ -1696,6 +2020,22 @@ module Tuile
       # _@return_ — true if a match was found.
       def select_prev: (String query, ?include_current: bool) -> bool
 
+      # Moves the cursor to the item at `index`, scrolling it into view and
+      # firing {#on_cursor_changed} — the positional member of the
+      # {#select_next} / {#select_prev} family, for a caller that already knows
+      # *which* item it wants:
+      # 
+      #   list.select(items.index(chosen))
+      # 
+      # Refuses an index the current {#cursor} can't reach — out of range, or
+      # anything at all under {Cursor::None} — rather than stranding the cursor
+      # off-content.
+      # 
+      # _@param_ `index`
+      # 
+      # _@return_ — whether the cursor moved there.
+      def select: (Integer index) -> bool
+
       # _@param_ `event`
       def handle_mouse: (MouseEvent event) -> void
 
@@ -2037,6 +2377,364 @@ 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
+    # {#on_tab_selected}.
+    # 
+    #   ␣Details␣│␣Payment␣│␣Shipping␣
+    #    ^^^^^^^   selected: bold, and highlighted while the strip has focus
+    # 
+    #   tabs = Component::Tabs.new
+    #   tabs.add_tab("Details")                # the first tab is selected
+    #   payment = tabs.add_tab("Payment")
+    #   tabs.on_tab_selected = ->(index, tab) { show(index) }
+    #   tabs.selected = payment                # fires the listener
+    #   payment.caption = "Payment ⚠"          # repaints the strip
+    # 
+    # LEFT / RIGHT switch tabs immediately — no cursor to move first, no Enter
+    # to confirm — clamping at both ends rather than wrapping; a left click
+    # selects the tab under the pointer. Everything else bubbles to an ancestor,
+    # Enter, Space, Up, Down, Home and End included, so a form's default button
+    # and the app's own keys keep working while the strip has focus.
+    # 
+    # One tab stop for the whole strip: Tab moves *past* it, never between its
+    # tabs. For a key of your own that switches tabs from elsewhere in the app,
+    # bind it yourself and call {#select_next} / {#select_previous}.
+    # 
+    # {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`.
+    # 
+    # == Sizing
+    # Assign a {#rect} (typically from the surrounding {Layout}). One wider than
+    # {#extent}`.width` leaves a dead tail; a narrower one **scrolls**. The strip
+    # keeps the selected segment whole in view, moving its window by the minimum
+    # needed, so arrowing into an off-screen tab brings that tab on screen — and
+    # a click on a half-visible segment at an edge selects it and pulls it into
+    # view. A `<` or `>` painted over an edge column says there is more strip
+    # that way, as does the cut caption underneath it. The one thing that cannot
+    # be shown whole is a caption wider than the entire rect: it shows its head
+    # and clips its tail. The scroll offset itself is not API — the invariant is.
+    # 
+    # == Implementation details
+    # A segment is one space of padding, the caption, one space of padding, and
+    # segments are joined by a single {DEFAULT_SEPARATOR} column. The padding
+    # belongs to the segment: the highlight covers it and a click on it selects
+    # the tab, while the separator column is chrome and selects nothing, like
+    # the blank tail past {#extent}. One private `segments` method is the sole
+    # source of that arithmetic — both the paint and the hit test read it, and
+    # both offset it by the same scroll column, so a click cannot land on a tab
+    # other than the one drawn under it — and it is
+    # derived from the captions on each call rather than recorded during the
+    # last paint, so a hit test is correct before the first paint.
+    # 
+    # The selected caption is bold *always*, so the strip still says where you
+    # are once focus has moved on, and additionally sits on
+    # {Theme#active_bg_color} while the strip is on the focus chain. Bold is the
+    # selection channel and not strip chrome: bolding every caption would leave
+    # selection to the focus-gated background alone, and an unfocused strip
+    # would then show no selection at all.
+    class Tabs < Component
+      DEFAULT_SEPARATOR: String
+
+      # _@param_ `separator` — see {#separator=}.
+      def initialize: (?separator: (String | StyledString)) -> void
+
+      # _@return_ — `true` — the strip takes focus, so its arrows work.
+      def focusable?: () -> bool
+
+      # _@return_ — `true` — one stop for the whole strip.
+      def tab_stop?: () -> bool
+
+      # _@return_ — the selected tab; `nil` only while there are no tabs.
+      def selected: () -> Tab?
+
+      # _@param_ `tab` — one of this strip's tabs.
+      def selected=: (Tab tab) -> void
+
+      # Appends a tab and returns its handle. The first tab added becomes the
+      # selection; later ones don't disturb it.
+      # 
+      # _@param_ `caption` — parsed as {Tab#caption=} parses it.
+      def add_tab: (?(String | StyledString)? caption) -> Tab
+
+      # Removes `tab` and detaches its handle permanently.
+      # 
+      # The selection is never left dangling: removing the selected tab selects
+      # whichever tab slid into its place (the new last tab, if it was the last),
+      # and removing the final tab leaves {#selected} `nil`. Either way
+      # {#on_tab_selected} fires — the empty case with `(nil, nil)`, since a
+      # listener rendering from the selection has to be told to render nothing.
+      # 
+      # _@param_ `tab` — one of this strip's tabs.
+      def remove_tab: (Tab tab) -> void
+
+      # Selects the next tab, clamping at the last — the strip never wraps.
+      # Public because it is the verb an app's own key binding drives.
+      # 
+      # _@return_ — `false` only when there are no tabs.
+      def select_next: () -> bool
+
+      # Selects the previous tab, clamping at the first.
+      # 
+      # _@return_ — `false` only when there are no tabs.
+      def select_previous: () -> bool
+
+      # The cells the strip actually paints: one row, as wide as its segments and
+      # separators need, clipped to {#rect}. A layout routinely hands a strip a
+      # window's full width for a 32-column strip — the extent is those 32
+      # columns.
+      # 
+      # Both the focus highlight and the click hit test use it, so a click on the
+      # 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: () -> 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
+      # bubbles to an ancestor; an empty strip handles nothing at all.
+      # 
+      # _@param_ `key`
+      def handle_key: (String key) -> bool
+
+      # Selects the tab under a left click; `super` runs first, so a click
+      # anywhere in {#rect} still focuses.
+      # 
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
+
+      def repaint: () -> void
+
+      # Re-syncs the scroll offset and repaints — what every change to the
+      # captions, the separator or the selection ends in.
+      def refresh: () -> void
+
+      # The rect's *width* is the only part of it the offset depends on, so this
+      # hook is the whole geometry story; {Component#rect=} invalidates for us.
+      def on_width_changed: () -> void
+
+      # Scrolls the minimum needed to show the selected segment whole, and is the
+      # sole writer of {#left_column}. Idempotent, so every mutation site can
+      # call it blindly; it returns the offset to `0` on its own once the strip
+      # fits again, which is why no mutator owes a scroll-back branch.
+      # 
+      # A segment wider than the whole rect cannot be shown whole: its head wins,
+      # being the half of a caption that identifies it.
+      def adjust_left_column: () -> void
+
+      # {StyledString#slice} *drops* a cluster straddling the window's edge
+      # rather than half-painting it, which would leave the painted row a column
+      # short and shift everything past the hole one column left — paint and hit
+      # test would then disagree, silently and only for wide glyphs. So the
+      # offset only ever lands on a cluster boundary. Snapping *forward* is the
+      # safe direction: it gives up at most one column of the segment to the left
+      # of the window, never of the one being revealed.
+      # 
+      # _@param_ `column`
+      # 
+      # _@return_ — the smallest cluster-boundary column `>= column`.
+      def snap_to_glyph_start: (Integer column) -> Integer
+
+      # Paints the overflow cues over the windowed row's edge columns: `<` when
+      # segments sit to the left of the window, `>` when more sit to the right.
+      # ASCII by convention rather than by constant, as {Checkbox}'s brackets
+      # are, and *overlaid* rather than given reserved columns — reserving would
+      # make the window width a function of the offset computed from it.
+      # 
+      # _@param_ `row` — the windowed row, as painted.
+      def draw_cues: (StyledString row) -> void
+
+      # The cue keeps the style of the cell it covers, so one landing on the
+      # selected segment doesn't punch a default-background hole in its
+      # highlight.
+      # 
+      # _@param_ `row` — the windowed row.
+      # 
+      # _@param_ `column` — relative to {#rect}`.left`.
+      # 
+      # _@param_ `glyph`
+      def draw_cue: (StyledString row, Integer column, String glyph) -> void
+
+      # One `[tab, start_column, width]` triple per tab, in strip order, in
+      # columns relative to {#rect}`.left`. A segment's width is its caption plus
+      # the two padding columns; the separator columns between segments belong to
+      # no segment.
+      def segments: () -> ::Array[[Tab, Integer, Integer]]
+
+      # _@return_ — columns the strip would paint given an unlimited rect.
+      def painted_width: () -> Integer
+
+      # _@param_ `point`
+      # 
+      # _@return_ — the tab painted at `point`; `nil` for a separator
+      # column, the blank tail, or a row the strip doesn't paint.
+      def tab_at: (Point point) -> Tab?
+
+      # _@return_ — the whole strip as one row, unclipped: segments
+      # left to right, joined by the separator. {#repaint} windows it to the
+      # rect; nothing else may, since the window's own arithmetic is
+      # {#adjust_left_column}'s.
+      def strip_row: () -> StyledString
+
+      # _@param_ `tab`
+      # 
+      # _@param_ `index`
+      # 
+      # _@return_ — the caption between its padding columns, styled
+      # for the selection.
+      def segment_text: (Tab tab, Integer index) -> StyledString
+
+      # _@param_ `tab`
+      # 
+      # _@return_ — the tab's position on this strip.
+      def index_of!: (Tab tab) -> Integer
+
+      # _@param_ `delta` — `+1` / `-1`.
+      # 
+      # _@return_ — `false` only when there are no tabs.
+      def step_selection: (Integer delta) -> bool
+
+      # _@param_ `index`
+      def select_at: (Integer? index) -> void
+
+      # Stores the selection, repaints, and fires {#on_tab_selected} when the
+      # selected *tab* changed.
+      # 
+      # `previous` is passed in rather than read here because a removal can leave
+      # the index numerically unchanged while a different tab sits under it —
+      # remove the selected middle tab of three and index 1 now holds what used
+      # to be index 2. Comparing indices would swallow that notification.
+      # 
+      # _@param_ `index` — the new selection.
+      # 
+      # _@param_ `previous` — the tab selected before the caller's change.
+      def apply_selection: (Integer? index, Tab? previous) -> void
+
+      # Called with `@tabs` already shortened and `@selected_index` still holding
+      # the pre-removal position.
+      # 
+      # _@param_ `removed_index` — the position the removed tab held.
+      # 
+      # _@return_ — where the selection lands.
+      def selection_after_removing: (Integer removed_index) -> Integer?
+
+      # Called on every change of {#selected} with the new selection —
+      # `(index, tab)`, or `(nil, nil)` once the last tab has been removed.
+      # 
+      # It reports that the selection *changed*, not that the user pressed
+      # something: arrows, a click, {#selected=} / {#selected_index=}, the
+      # autoselect of the first {#add_tab} and the re-selection that follows
+      # removing the selected tab all fire it. Re-selecting the tab already
+      # selected fires nothing.
+      attr_accessor on_tab_selected: Proc?
+
+      # _@return_ — the tabs, in strip order. Read-only by convention
+      # (like {Component#children}) — grow and shrink it through {#add_tab} /
+      # {#remove_tab}, which keep the selection consistent. Enumerate it to
+      # find a tab: `tabs.find { |t| t.caption.to_s == "Payment" }`.
+      attr_reader tabs: ::Array[Tab]
+
+      # _@return_ — the column painted between two segments.
+      attr_accessor separator: (StyledString | String)
+
+      # _@return_ — the selected tab's position; `nil` only while
+      # there are no tabs.
+      attr_accessor selected_index: Integer?
+
+      # _@return_ — the strip column painted in {#rect}'s leftmost cell —
+      # the horizontal scroll offset. `0` unless the strip overflows its rect;
+      # {#adjust_left_column} is its sole writer.
+      attr_reader left_column: Integer
+
+      # A single tab: a caption, plus its identity on the strip.
+      # 
+      #   tab = tabs.add_tab("Payment")
+      #   tab.caption = "Payment ⚠"   # repaints the strip
+      #   tab.remove                  # `tab` now raises on every mutator
+      # 
+      # Apps don't construct tabs; {Tabs#add_tab} mints them. A removed handle
+      # raises {RuntimeError} on every mutator and on every reader that consults
+      # the strip — answering confidently about a tab the strip no longer holds
+      # would hide the bug. {#caption} and {#attached?} stay readable (the
+      # caption lives here, so an error message can still name it), and
+      # {#remove} is a silent no-op so a cleanup path can call it blindly.
+      class Tab
+        # _@param_ `strip` — the owning strip.
+        # 
+        # _@param_ `caption` — already coerced by the caller.
+        def initialize: (Tabs strip, StyledString caption) -> void
+
+        # _@return_ — `true` while the tab is owned by its {Tabs}; `false`
+        # permanently once removed.
+        def attached?: () -> bool
+
+        # _@return_ — whether this is the strip's selected tab.
+        def selected?: () -> bool
+
+        # Removes this tab from its strip and detaches the handle permanently —
+        # {Tabs#remove_tab} has what that does to the selection. Idempotent on an
+        # already-removed tab, unlike the mutators.
+        def remove: () -> void
+
+        def inspect: () -> String
+
+        def detach: () -> void
+
+        def check_attached: () -> void
+
+        # _@return_ — the label painted on the strip. Safe to read on
+        # a removed tab.
+        attr_accessor caption: (StyledString | String)?
+      end
+    end
+
     # A label which shows static text. No word-wrapping; long lines are
     # truncated with an ellipsis. Text is modeled as a {StyledString};
     # {#text=} accepts a {String} (parsed via {StyledString.parse}, so
@@ -2085,105 +2783,71 @@ 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.
-    class Popup < Component
-      include Tuile::Component::HasContent
-
+    # nested {Component::TextField} doesn't dismiss the popup: the field consumes
+    # it first.
+    # 
+    # 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}.
-      def initialize: (?content: Component?, ?modal: bool, ?size: (Size | Fraction)) -> 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
 
+      # _@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
 
       # Recenters the popup on the screen, preserving its current width/height.
       def center: () -> void
 
-      # Hint for the status bar: own "q Close" plus the wrapped content's hint.
-      def keyboard_hint: () -> String
-
       # `q` and ESC close the popup. The popup sits on the focus chain of
       # whatever it wraps, so the key reaches here by bubbling up from the
       # focused content after that content declined to handle it.
@@ -2193,18 +2857,14 @@ module Tuile
       # _@return_ — true if the key was handled.
       def handle_key: (String key) -> bool
 
-      # 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 {#declared_size=}.
+      attr_accessor declared_size: (Size | Fraction)
     end
 
     # A clickable button. Activated by Enter, Space, or a left mouse click;
@@ -2240,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.
@@ -2303,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},
@@ -2739,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
@@ -2765,8 +3420,6 @@ module Tuile
 
       def tab_stop?: () -> bool
 
-      def keyboard_hint: () -> String
-
       # Re-anchors the (open) dropdown after a move or resize.
       # 
       # _@param_ `new_rect`
@@ -2788,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.
       # 
@@ -2857,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.
@@ -2887,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
@@ -2939,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
@@ -2959,17 +3633,169 @@ 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 boolean input on one row. Space, Enter or a left click toggles it:
+    # 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
     #   [ ] Enable syslog forwarding
@@ -3051,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.
@@ -3093,10 +3919,499 @@ 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
 
+    # A one-row strip of menu captions, each dropping open a cascade of submenus
+    # that nests as deep as you build it.
+    # 
+    #   ␣File␣␣Edit␣␣View␣          <- the strip; highlighted while focused
+    #    ␣New␣␣␣␣␣␣␣␣␣              <- the open menu, measured to its widest label
+    #    ␣Recent␣␣␣␣▸␣              <- a row that opens a submenu
+    #    ␣Quit␣␣␣␣␣␣␣␣              (the outer gutters are {List}'s)
+    # 
+    #   bar = Component::MenuBar.new
+    #   file = bar.add_item("File", mnemonic: "f")
+    #   file.add_item("New", mnemonic: "n") { new_document }
+    #   recent = file.add_item("Recent")            # no block ⇒ a submenu holder
+    #   recent.add_item("notes.txt") { open("notes.txt") }
+    #   bar.add_item("Quit") { screen.close }       # a top-level leaf: a button
+    # 
+    # LEFT / RIGHT move along the strip; Enter, Space or Down opens the
+    # highlighted menu. Inside a menu: Up / Down (and PgUp/PgDn, Ctrl+U/D) move
+    # the highlight, Enter or Space activates a row or opens its submenu, RIGHT
+    # opens a submenu, LEFT returns to the previous menu, ESC closes one level.
+    # LEFT at the first level and RIGHT on a row with no submenu step to the
+    # sibling menu, as they do in every menu bar. Book ch7 has the table.
+    # 
+    # == Mnemonics
+    # An item given a `mnemonic:` answers to that letter, underlined in its
+    # caption wherever it occurs — on the strip and in the panels, focused or
+    # not (there is no Alt key to reveal them with). Matching is **level-scoped
+    # with no fallback**: the top-level items while the cascade is closed, the
+    # deepest open panel's items while it is open, and nothing else is ever
+    # consulted. So `f` then `q` walks File ▸ Quit as two ordinary keystrokes,
+    # two items on *different* levels may share a letter with nothing to
+    # arbitrate, and only siblings compete — a duplicate among them raises at
+    # {#add_item}. A letter matching nothing on the live level is swallowed and
+    # rings {Screen#beep}; it never falls out to a shallower level and switches
+    # menus. A mnemonic shadows what the app (or an ancestor, including a
+    # {Popup}'s `q`-to-close) would do with that key while the bar has focus.
+    # A paste can never fire one — pasted text rides its own path off the key
+    # ladder.
+    # 
+    # {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`.
+    # 
+    # == Sizing
+    # Assign a {#rect} (typically one {Layout::Fixed}`[1]` row at the top of a
+    # {Layout::Vertical}). One wider than {#extent}`.width` leaves a dead tail; a
+    # narrower one **scrolls** to keep the highlighted segment whole, cueing the
+    # hidden captions with a `<` or `>` over an edge column, exactly as {Tabs}
+    # does — so a bar wider than its terminal stays wholly reachable by arrow,
+    # mnemonic and click. Reassigning the rect
+    # **closes** an open cascade: every panel position is derived from a segment
+    # or a parent row, so after a resize they would all sit at stale columns, and
+    # a resize with a menu open is rare enough that closing beats re-anchoring
+    # every level.
+    # 
+    # == Implementation details
+    # Deliberately painted *unlike* {Tabs}, whose picture it would otherwise
+    # share: no separator between segments, no bold, and no highlight at all
+    # while unfocused — a menu bar has no persistent selection to show, and a
+    # reader should not have to work out which of the two controls they are
+    # looking at. Hit testing *is* {Tabs}': one private `segments` method feeds
+    # both the paint and the click and both offset it by the same scroll column,
+    # so a click cannot land on a caption other than the one drawn under it, and it is derived from the captions on each
+    # call so a hit test is correct before the first paint.
+    # 
+    # The open panels are overlays owned by a private {Cascade}, not children:
+    # focus stays here for the whole interaction, so the strip receives every key
+    # and forwards it. An open cascade swallows keys the cascade doesn't
+    # recognize; a *closed* strip lets every printable bubble, so an app's
+    # `s`-to-save keeps working while the bar has focus.
+    # 
+    # A click outside an open cascade is not blocked — non-modal overlays block
+    # nothing — but any click on a focusable component moves focus, and losing
+    # focus closes the cascade.
+    # 
+    # UI-thread-confined, like every component (see {Screen}).
+    class MenuBar < Component
+      def initialize: () -> void
+
+      # _@return_ — `true` — the strip takes focus, so its keys work.
+      def focusable?: () -> bool
+
+      # _@return_ — `true` — one stop for the whole strip, as on {Tabs}.
+      def tab_stop?: () -> bool
+
+      # _@return_ — the top-level items, in strip order. Read-only by
+      # convention; grow it through {#add_item}.
+      def items: () -> ::Array[Item]
+
+      # Appends a top-level item and returns its handle; nest submenus into it
+      # with {Item#add_item}.
+      # 
+      # _@param_ `caption` — parsed as {StyledString.parse} parses it.
+      # 
+      # _@param_ `mnemonic` — a single one-column printable character that activates this item while the strip is focused and *closed*, underlined in the caption where it occurs. Matched case-insensitively; it shadows whatever the app would otherwise do with that key while the bar has focus.
+      def add_item: (?(String | StyledString)? caption, ?mnemonic: String?) -> Item
+
+      # The cells the strip actually paints: one row, as wide as its segments
+      # need, clipped to {#rect}.
+      # 
+      # Both the highlight and the click hit test use it, so a click on the blank
+      # 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: () -> Size
+
+      # _@param_ `new_rect`
+      def rect=: (Rect new_rect) -> void
+
+      # Closes the cascade when the strip leaves the focus chain, so tabbing (or
+      # clicking) away doesn't strand an open menu.
+      # 
+      # _@param_ `flag`
+      def active=: (bool flag) -> void
+
+      # Closes the cascade, so a bar removed from the tree can't strand its
+      # panels on the pane — they are the {ScreenPane}'s children, not the bar's,
+      # so nothing else would take them down.
+      def on_detached: () -> void
+
+      # Offers the key to the open cascade first, then to the strip's own
+      # LEFT/RIGHT/Enter/Space/Down.
+      # 
+      # With a cascade open, the only keys reaching the strip are the two the
+      # cascade declines — LEFT at the first level, RIGHT on a row with no
+      # submenu — and both step to the sibling menu.
+      # 
+      # _@param_ `key`
+      def handle_key: (String key) -> bool
+
+      # Opens the menu under a left click, or closes it when it is already the
+      # open one; `super` runs first, so a click anywhere in {#rect} still
+      # focuses.
+      # 
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
+
+      def repaint: () -> void
+
+      # The sole writer of {#highlighted_index}: assigns, re-syncs the scroll
+      # offset and repaints. Every path that moves the highlight — arrow,
+      # mnemonic, click — goes through it, so the highlighted segment is on
+      # screen *before* {Cascade} anchors a panel to it.
+      # 
+      # _@param_ `index`
+      def highlight=: (Integer index) -> void
+
+      # Re-syncs the scroll offset and repaints — what every change to the items
+      # or the highlight ends in.
+      def refresh: () -> void
+
+      # The rect's *width* is the only part of it the offset depends on, so this
+      # hook is the whole geometry story; {Component#rect=} invalidates for us,
+      # and {#rect=} closes the cascade rather than re-anchoring it.
+      def on_width_changed: () -> void
+
+      # Scrolls the minimum needed to show the highlighted segment whole, and is
+      # the sole writer of {#left_column}. Idempotent, so every mutation site can
+      # call it blindly; it returns the offset to `0` on its own once the strip
+      # fits again, which is why no mutator owes a scroll-back branch.
+      # 
+      # A segment wider than the whole rect cannot be shown whole: its head wins,
+      # being the half of a caption that identifies it.
+      def adjust_left_column: () -> void
+
+      # {StyledString#slice} *drops* a cluster straddling the window's edge
+      # rather than half-painting it, which would leave the painted row a column
+      # short and shift everything past the hole one column left — paint and hit
+      # test would then disagree, silently and only for wide glyphs. So the
+      # offset only ever lands on a cluster boundary. Snapping *forward* is the
+      # safe direction: it gives up at most one column of the segment to the left
+      # of the window, never of the one being revealed.
+      # 
+      # _@param_ `column`
+      # 
+      # _@return_ — the smallest cluster-boundary column `>= column`.
+      def snap_to_glyph_start: (Integer column) -> Integer
+
+      # Paints the overflow cues over the windowed row's edge columns: `<` when
+      # segments sit to the left of the window, `>` when more sit to the right.
+      # ASCII by convention rather than by constant, as {Checkbox}'s brackets
+      # are, and *overlaid* rather than given reserved columns — reserving would
+      # make the window width a function of the offset computed from it. Painted
+      # focused or not: overflow is a fact about the captions and the rect, not
+      # about focus.
+      # 
+      # _@param_ `row` — the windowed row, as painted.
+      def draw_cues: (StyledString row) -> void
+
+      # The cue keeps the style of the cell it covers, so one landing on the
+      # highlighted segment doesn't punch a default-background hole in its
+      # highlight.
+      # 
+      # _@param_ `row` — the windowed row.
+      # 
+      # _@param_ `column` — relative to {#rect}`.left`.
+      # 
+      # _@param_ `glyph`
+      def draw_cue: (StyledString row, Integer column, String glyph) -> void
+
+      # One `[item, start_column, width]` triple per top-level item, in strip
+      # order, in columns relative to {#rect}`.left`. A segment is its caption
+      # between two padding columns, and neighbours abut — the two blank columns
+      # between captions are the segments' own padding, so a click on either
+      # opens the menu it belongs to.
+      def segments: () -> ::Array[[Item, Integer, Integer]]
+
+      # _@return_ — columns the strip would paint given an unlimited rect.
+      def painted_width: () -> Integer
+
+      # _@param_ `point`
+      # 
+      # _@return_ — the index of the item painted at `point`; `nil`
+      # for the blank tail or a row the strip doesn't paint.
+      def index_at: (Point point) -> Integer?
+
+      # _@param_ `index`
+      # 
+      # _@return_ — the segment's cells on screen — the cascade's anchor.
+      def segment_rect: (Integer index) -> Rect
+
+      # _@return_ — the whole strip as one row, unclipped. {#repaint}
+      # windows it to the rect; nothing else may, since the window's own
+      # arithmetic is {#adjust_left_column}'s.
+      def strip_row: () -> StyledString
+
+      # _@param_ `item`
+      # 
+      # _@param_ `index`
+      # 
+      # _@return_ — the caption between its padding columns,
+      # highlighted when it is the one Enter would open *and* the strip has
+      # focus. An unfocused strip shows no highlight at all: there is no
+      # persistent selection to report.
+      def segment_text: (Item item, Integer index) -> StyledString
+
+      # Activates the item bound to `key` on the *live* level — the deepest open
+      # panel while the cascade is open, the top-level strip while it is closed.
+      # No fallback between the two: a letter matching nothing in the live set is
+      # not offered to any other level.
+      # 
+      # _@param_ `key`
+      # 
+      # _@return_ — whether a mnemonic claimed the key.
+      def handle_mnemonic: (String key) -> bool
+
+      # Moves the highlight along the strip, clamping at both ends. Consumes the
+      # key even at an end, as {Tabs} does.
+      # 
+      # _@param_ `delta` — `+1` / `-1`.
+      # 
+      # _@return_ — `false` only when there are no items.
+      def move_highlight: (Integer delta) -> bool
+
+      # Steps to the neighbouring menu, showing *its* menu instead — or closing
+      # the cascade, when the neighbour is a top-level button with no menu to
+      # show. The cascade is left alone when the highlight is already at an end:
+      # reopening the same menu would throw away the submenu the user is standing
+      # in.
+      # 
+      # It deliberately never *activates*. An item arrowed past is highlighted,
+      # not pressed, so a top-level button waits for Enter or Space — otherwise
+      # walking the strip would fire every button on it.
+      # 
+      # _@param_ `delta` — `+1` / `-1`.
+      # 
+      # _@return_ — always `true`: an open menu swallows the key either way.
+      def step_menu: (Integer delta) -> bool
+
+      # Opens the highlighted item's menu, or fires it when it is a top-level
+      # button — the Enter/Space/Down/click path, and the only one that fires a
+      # listener.
+      # 
+      # _@return_ — `false` only when there are no items.
+      def open_highlighted: () -> bool
+
+      # Shows the highlighted item's menu, closing the cascade when it has none.
+      def show_highlighted_menu: () -> void
+
+      # _@return_ — which top-level item the strip highlights while
+      # focused, and which menu Enter opens. `0` until the user moves.
+      attr_reader highlighted_index: Integer
+
+      # _@return_ — the strip column painted in {#rect}'s leftmost cell —
+      # the horizontal scroll offset. `0` unless the strip overflows its rect;
+      # {#adjust_left_column} is its sole writer.
+      attr_reader left_column: Integer
+
+      # One menu item: a caption, an optional click listener, and its children.
+      # 
+      #   file = bar.add_item("File")       # minted by the bar
+      #   file.add_item("New") { create }   # …and nested by the same method
+      #   file.items.size                   # => 1
+      # 
+      # An item with children is a submenu and its own listener is dead
+      # ({#submenu?} decides). An item with **neither** children nor a listener is
+      # legal and inert: it highlights, Enter closes the menu, nothing happens —
+      # an item that looks live but does nothing is the app's error to fix, not
+      # the framework's to raise on.
+      # 
+      # Apps don't construct items; {MenuBar#add_item} and {#add_item} do.
+      class Item
+        # _@param_ `caption` — already coerced by the caller.
+        # 
+        # _@param_ `mnemonic` — already validated by the caller, in the case it was given in.
+        # 
+        # _@param_ `on_click`
+        def initialize: (StyledString caption, String? mnemonic, (Proc | Method)? on_click) -> void
+
+        # _@return_ — whether this item opens a submenu, i.e. has children.
+        def submenu?: () -> bool
+
+        # Appends a child and returns its handle.
+        # 
+        # _@param_ `caption` — parsed as {StyledString.parse} parses it.
+        # 
+        # _@param_ `mnemonic` — the letter that activates this child while *this* item's children are the live level; see {MenuBar#add_item}.
+        def add_item: (?(String | StyledString)? caption, ?mnemonic: String?) -> Item
+
+        def inspect: () -> String
+
+        # Rejects a mnemonic that couldn't work, or that would make two siblings
+        # ambiguous — all three at *registration*, since none has a sane answer
+        # at keypress time.
+        # 
+        # _@param_ `mnemonic`
+        def validate_mnemonic: (String? mnemonic) -> void
+
+        # {StyledString#slice} counts **columns** while a caption search yields a
+        # **character** index, so the prefix is measured, never counted.
+        # 
+        # _@param_ `caption`
+        # 
+        # _@param_ `mnemonic` — in the case it was given in.
+        def build_cued_caption: (StyledString caption, String? mnemonic) -> StyledString
+
+        # _@return_ — the label painted on the strip or the row.
+        attr_reader caption: StyledString
+
+        # _@return_ — the downcased letter that activates this item
+        # while its own level is the live one; `nil` when it has none.
+        attr_reader mnemonic: String?
+
+        # _@return_ — {#caption} with the {#mnemonic} underlined —
+        # what both paint sites draw. Equal to {#caption} when there is no
+        # mnemonic or the caption doesn't contain it. Computed once, at
+        # construction: caption and mnemonic are both fixed there, and
+        # underline is a plain attribute with no theme or `bg_color` input, so
+        # this is not a cached theme value.
+        attr_reader cued_caption: StyledString
+
+        # _@return_ — this item's children, in menu order. Read-only by
+        # convention, like {Component#children} — grow it through {#add_item}.
+        attr_reader items: ::Array[Item]
+
+        # _@return_ — no-arg callable fired when the item is
+        # activated (Enter, Space or a left click), exactly as
+        # {Button#on_click}. Never fired on an item with children.
+        attr_accessor on_click: (Proc | Method)?
+      end
+
+      # The stack of open menu panels — one {ListDropdown} per level, the last
+      # deepest — and the drill/pop/activate logic driving them. Private
+      # machinery of {MenuBar}; an app never names it.
+      # 
+      #   cascade.open_below(segment_rect, item)   # Enter/Down on the strip
+      #   return true if cascade.handle_key(key)   # MenuBar#handle_key, first
+      #   cascade.close                            # focus lost, or rect changed
+      # 
+      # A panel is a **non-modal overlay, not a child**, so it never takes focus:
+      # focus stays on the {MenuBar} for the whole interaction and every key
+      # arrives via {MenuBar#handle_key}, which offers it here first. That is
+      # {Component::Select}'s architecture extended to N levels, and it is why
+      # nothing in the key-dispatch ladder changes.
+      # 
+      # 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`).
+      # 
+      # == Implementation details
+      # While open it consumes **everything** except the two keys that mean
+      # "leave this menu sideways", which only the strip can answer: LEFT at
+      # depth 1, and RIGHT on a row with no submenu. An open menu is quasi-modal
+      # — firing an app's `s`-to-save behind a visible panel is worse than a dead
+      # keystroke.
+      # 
+      # UI-thread-confined, like everything in the tree (see {Screen}).
+      class Cascade
+        SUBMENU_ARROW: String
+        ARROW_WIDTH: Integer
+
+        def initialize: () -> void
+
+        # _@return_ — whether any panel is open.
+        def open?: () -> bool
+
+        # _@return_ — how many panels are open; `0` when closed.
+        def depth: () -> Integer
+
+        # Opens `item`'s children directly beneath `anchor`, closing anything
+        # already open first.
+        # 
+        # _@param_ `anchor` — the strip segment the menu drops from.
+        # 
+        # _@param_ `item` — a childless one opens nothing.
+        def open_below: (Rect anchor, Item item) -> void
+
+        # Closes every open panel, deepest first.
+        def close: () -> void
+
+        # Offers a key to the deepest panel and to the cascade's own verbs.
+        # 
+        # _@param_ `key`
+        # 
+        # _@return_ — `true` when consumed — almost always, while open.
+        # `false` when closed, and for the two sideways keys {MenuBar} answers
+        # (see the class docs).
+        def handle_key: (String key) -> bool
+
+        # Activates the deepest level's item bound to `key` — the drill-or-fire
+        # the mnemonic shares with Enter. The highlight moves there *first*, so a
+        # submenu anchors beside the row that opened it rather than beside
+        # wherever the cursor happened to be.
+        # 
+        # _@param_ `key` — a single printable, already downcased.
+        # 
+        # _@return_ — whether an item on the deepest level claimed it. A
+        # miss is never offered to a shallower level.
+        def handle_mnemonic: (String key) -> bool
+
+        # _@return_ — the deepest open panel.
+        def deepest: () -> ListDropdown
+
+        def activate_highlighted: () -> void
+
+        # Drills into `item`, or fires it and closes the cascade.
+        # 
+        # _@param_ `level` — the panel the item belongs to.
+        # 
+        # _@param_ `item` — `nil` (an off-content cursor) does nothing.
+        def activate: (Integer level, Item? item) -> void
+
+        # Opens `item`'s children beside the row highlighted in `level`.
+        # 
+        # _@param_ `level`
+        # 
+        # _@param_ `item`
+        def push_beside: (Integer level, Item item) -> void
+
+        # Mounts a panel for `item`'s children and yields it for geometry.
+        # 
+        # _@param_ `item`
+        def push: (Item item) ?{ (ListDropdown drop, Integer rows, Integer width) -> void } -> void
+
+        # Closes the deepest panel; at depth 1 that closes the cascade.
+        def pop: () -> void
+
+        # _@param_ `count` — how many panels to keep.
+        def truncate: (Integer count) -> void
+
+        # _@param_ `level`
+        # 
+        # _@return_ — the item under `level`'s cursor; `nil` when it sits
+        # off-content. The range guard matters: a cursor at `-1` would
+        # otherwise index the *last* child.
+        def highlighted: (Integer level) -> Item?
+
+        # _@param_ `items`
+        # 
+        # _@return_ — item -> row: the label padded to the level's widest, plus
+        # an arrow column when any sibling has a submenu — so every arrow lands
+        # in the same column without asking the {List} how wide it ended up.
+        def renderer_for: (::Array[Item] items) -> Proc
+
+        # _@param_ `items`
+        # 
+        # _@return_ — the panel width: the rendered row plus {List}'s two
+        # row gutters, plus a scrollbar column when the rows can't all be shown.
+        # As in {Component::Select}, the scrollbar is predicted from the item
+        # count rather than the final height — a panel the screen clamps
+        # shorter than {ListDropdown::MAX_VISIBLE_ROWS} scrolls without having
+        # bought that column, and ellipsizes one character early.
+        def width_for: (::Array[Item] items) -> Integer
+
+        # _@param_ `items`
+        def label_width_of: (::Array[Item] items) -> Integer
+      end
+    end
+
     # A text field with a filtering dropdown: type to narrow the candidates,
     # arrow to move the highlight, Enter (or click) to accept. Its {#value} is
     # the *selected item* — of whatever type the items are — not the display
@@ -3109,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.
     # 
@@ -3144,8 +4459,6 @@ module Tuile
       # hardware cursor to its field).
       def cursor_position: () -> Point?
 
-      def keyboard_hint: () -> String
-
       # Re-anchors the (open) dropdown after {HasContent#rect=} has resized the
       # field via {#layout}.
       # 
@@ -3166,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.
@@ -3248,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
@@ -3304,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
@@ -3312,6 +4631,158 @@ module Tuile
       attr_accessor on_value_change: (Proc | Method)?
     end
 
+    # A {Component::Tabs} strip on its top row plus the pane belonging to the
+    # selected tab underneath it:
+    # 
+    #   ␣Details␣│␣Payment␣│␣Shipping␣
+    #   the selected tab's pane fills the rest of the rect
+    # 
+    #   sheet = Component::TabSheet.new
+    #   sheet.add_tab("Details", details_form)     # selected, and shown
+    #   sheet.add_tab("Payment", payment_form)
+    #   sheet.select_next                          # shows payment_form
+    #   sheet.on_tab_selected = ->(index, tab) { log("now on #{tab&.caption}") }
+    # 
+    # Tab lands on the strip first and enters the pane on the next press, which
+    # is the browser's order; switching tabs does *not* move focus into the new
+    # pane, but if focus was inside the pane that just went away it lands back
+    # on the strip.
+    # 
+    # == Hidden panes are detached
+    # Only the selected tab's pane is in the component tree — the others are
+    # detached, which is how Tuile hides a component (there is no visibility
+    # flag, and an empty rect gates painting only). Consequences worth
+    # designing around:
+    # 
+    # - A hidden pane is invisible to *everything*: the Tab cycle, focus
+    #   cascades, repaint, the cursor, `on_tree` walks. No gates anywhere.
+    # - Its state survives, because state is ivars — scroll position, caret,
+    #   list cursor, text are all exactly as the user left them, and mutating a
+    #   hidden pane is safe (`invalidate` while detached is a silent no-op).
+    # - {Component#on_detached} / {Component#on_attached} fire on every switch,
+    #   so a pane holding a mounted-lifetime resource — a {Component::ProgressBar}'s
+    #   ticker — releases it while hidden and re-acquires it on return. A pane
+    #   that must keep something alive while hidden can't; that something
+    #   belongs in the model the pane renders, not in the pane.
+    # 
+    # == Implementation details
+    # `children` is `[strip, pane]`, the strip pinned at index 0, so pre-order
+    # traversal gives the strip-then-pane Tab order for free. The swap follows
+    # the slot-swap recipe {Component#detach_child} documents — detach, rewire,
+    # `on_child_removed` last, so the focus repair sees the new occupant.
+    # 
+    # Panes live in an identity-keyed `Tab => Component` map here rather than in
+    # a slot on {Tabs::Tab}: the strip's tab array stays the sole ordering
+    # authority, and the strip itself stays ignorant of panes. One idempotent
+    # `sync_pane` is the sole writer of the visible pane, deriving it from
+    # `strip.selected` on every call, so registering a pane and selecting a tab
+    # can happen in either order.
+    # 
+    # The sheet owns the strip's `on_tab_selected` (that is what drives the
+    # swap); an app's listener goes on {#on_tab_selected} here, which fires
+    # after the pane has been swapped in.
+    class TabSheet < Component
+      # _@param_ `separator` — the strip's separator; see {Tabs#separator=}.
+      def initialize: (?separator: (String | StyledString)) -> void
+
+      # Adds a tab and the pane to show while it is selected. The first tab
+      # added becomes the selection, so its pane is shown immediately.
+      # 
+      # _@param_ `caption` — parsed as {Tabs::Tab#caption=} parses it.
+      # 
+      # _@param_ `pane` — shown while this tab is selected, detached while it isn't.
+      # 
+      # _@return_ — the new tab's handle.
+      def add_tab: ((String | StyledString)? caption, Component pane) -> Tabs::Tab
+
+      # Removes a tab and forgets its pane, detaching it if it was the visible
+      # one. The strip re-selects as {Tabs#remove_tab} describes, and this
+      # sheet shows whatever it lands on.
+      # 
+      # _@param_ `tab` — one of this sheet's tabs.
+      # 
+      # _@return_ — the pane that tab owned.
+      def remove_tab: (Tabs::Tab tab) -> Component?
+
+      # _@param_ `tab`
+      # 
+      # _@return_ — the pane registered for `tab`; `nil` for a
+      # removed tab, a tab of another sheet, or `nil`.
+      def pane_for: (Tabs::Tab? tab) -> Component?
+
+      # _@return_ — the strip's tabs, in order.
+      def tabs: () -> ::Array[Tabs::Tab]
+
+      # _@return_ — the selected tab.
+      def selected: () -> Tabs::Tab?
+
+      # _@param_ `tab` — one of this sheet's tabs.
+      def selected=: (Tabs::Tab tab) -> void
+
+      # _@return_ — the selected tab's position.
+      def selected_index: () -> Integer?
+
+      # _@param_ `index` — a position in `0...tabs.size`.
+      def selected_index=: (Integer index) -> void
+
+      # Selects the next tab, clamping at the last one.
+      # 
+      # _@return_ — `false` only when there are no tabs.
+      def select_next: () -> bool
+
+      # Selects the previous tab, clamping at the first one.
+      # 
+      # _@return_ — `false` only when there are no tabs.
+      def select_previous: () -> bool
+
+      # _@param_ `new_rect`
+      def rect=: (Rect new_rect) -> 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
+
+      # Lands focus on the strip rather than on `self` when the focused pane is
+      # swapped out — a bare container can't use keys, and the user's last
+      # action was a tab switch.
+      # 
+      # _@param_ `child`
+      def on_child_removed: (Component child) -> void
+
+      # Makes the visible pane match `strip.selected`, swapping if it doesn't.
+      # Idempotent and the sole writer of `@pane`: it derives everything from
+      # current state, so {#add_tab} can register a pane after the strip has
+      # already selected its tab.
+      def sync_pane: () -> void
+
+      # Drops entries whose tab is gone. {Tabs::Tab#remove} takes a tab off the
+      # strip without passing through {#remove_tab}, and a detached tab can never
+      # be selected again, so its entry is dead weight — it pins the pane against
+      # garbage collection and makes {#add_tab} reject that pane as still in use.
+      # Idempotent and the only cleaner, because the rule it enforces is an
+      # invariant ("every key is a live tab of my strip") rather than a step in
+      # one code path.
+      def forget_removed_tabs: () -> void
+
+      def layout_pane: () -> void
+
+      # An app's own selection listener, called after the pane has been swapped
+      # in — `(index, tab)`, or `(nil, nil)` once the last tab is gone. Same
+      # contract as {Tabs#on_tab_selected}: it reports that the selection
+      # changed, whatever changed it.
+      attr_accessor on_tab_selected: Proc?
+
+      # _@return_ — the strip. Reach through it for the rest of its API —
+      # `sheet.strip.separator = "|"` — but leave its `on_tab_selected` alone:
+      # the sheet drives the pane swap through it, and {#on_tab_selected} is
+      # where an app's listener goes.
+      attr_reader strip: Tabs
+
+      # _@return_ — the pane currently in the tree — the selected
+      # tab's, `nil` while the sheet has no tabs.
+      attr_reader pane: Component?
+    end
+
     # A multi-line, word-wrapping text input.
     # 
     # Sized by the caller — {#rect} is fixed; the area does not grow with
@@ -3327,10 +4798,11 @@ module Tuile
     # start of the next row in nearly all cases).
     # 
     # Enter inserts a newline, as in a plain `<textarea>` or text editor; only
-    # {#on_change} is wired. A pasted line break arrives as `\n`
-    # ({Keys::CTRL_J}) rather than the `\r` a typed Enter sends, so both are
-    # accepted — otherwise a multi-line paste would silently lose its
-    # newlines.
+    # {#on_change} is wired. {Keys::CTRL_J} does the same, since that is the
+    # byte a terminal sends for a typed Ctrl+J. A *pasted* line break arrives
+    # through {AbstractStringField#handle_paste} instead and never as a key at
+    # all — so a subclass rebinding Enter to submit keeps working under a
+    # multi-line paste, which lands as one draft.
     # 
     # Up/Down move the caret between rows and, at the first/last row, snap to
     # the start/end of the text. A subclass can claim the key at that edge
@@ -3756,8 +5228,10 @@ module Tuile
 
       # Scrolls up half a viewport (`rect.height / 2`, at least one row),
       # clamped at the top — unlike {#scroll_top_row=}, which raises below `0`.
-      # What `Ctrl+U` does, minus the focus: {#handle_key} ignores every key
-      # while the view is inactive, this works whoever holds focus.
+      # What `Ctrl+U` does, minus the focus: dispatch delivers keys only along
+      # the focus chain, so this is what a host with focus elsewhere — a chat
+      # transcript under an input field — calls instead of forwarding a
+      # synthetic keystroke that would lie about where focus is.
       def scroll_half_page_up: () -> void
 
       # The `Ctrl+D` twin of {#scroll_half_page_up}, clamped at the last row —
@@ -3768,6 +5242,11 @@ module Tuile
 
       def tab_stop?: () -> bool
 
+      # Claims the scroll ladder: the arrows and `j`/`k`, PageUp/PageDown,
+      # `Ctrl+U`/`Ctrl+D`, Home/`g`/End/`G`. Acts on the key alone — a clamped
+      # scroll at either edge is still a handled key, and hand-feeding a key to
+      # an unfocused view scrolls it (dispatch gates on focus, this doesn't).
+      # 
       # _@param_ `key`
       def handle_key: (String key) -> bool
 
@@ -4132,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
@@ -4188,8 +5648,8 @@ module Tuile
     # 
     # - an **index** counts characters into {#text} — {#caret},
     #   {#max_text_length}, `text[i]`, every edit;
-    # - a **column** counts terminal cells — {#rect}, {#left_column},
-    #   {#cursor_position}, a {MouseEvent}.
+    # - a **column** counts terminal cells — {#rect}, {#cursor_position}, a
+    #   {MouseEvent}, and the private horizontal scroll offset `left_column`.
     # 
     # They coincide only while every glyph is one column wide. A fullwidth CJK
     # char is two columns and a combining mark zero, so index 3 of `"日本語"` is
@@ -4223,6 +5683,14 @@ module Tuile
       # _@param_ `key`
       def handle_text_input_key: (String key) -> bool
 
+      # Flattens the paste onto the field's one row — newlines become spaces —
+      # and trims it to what {#max_text_length} still allows. Trimming rather
+      # than rejecting: a paste that overshoots the cap fills the field, which
+      # is what typing the same characters would have done.
+      # 
+      # _@param_ `text`
+      def preprocess_paste: (String text) -> String
+
       def on_text_mutated: () -> void
 
       def on_caret_mutated: () -> void
@@ -4290,10 +5758,6 @@ module Tuile
       # _@return_ — maximum characters, or nil for unbounded (default).
       attr_accessor max_text_length: Integer?
 
-      # _@return_ — text column drawn in the field's leftmost cell — the
-      # horizontal scroll offset. Follows {#caret}, always on a glyph boundary.
-      attr_reader left_column: Integer
-
       # Optional callback fired when the UP arrow key is pressed. When set, UP
       # is consumed by the field; when nil, UP falls through to the parent
       # (default behavior). Only triggered by {Keys::UP_ARROW}, not by `k`,
@@ -4316,6 +5780,15 @@ module Tuile
       # 
       # _@return_ — no-arg callable, or nil.
       attr_accessor on_enter: (Proc | Method)?
+
+      # Internal — the field's own scroll state, with no caller outside this
+      # class: the paint, the cursor and the hit test all read the ivar, and
+      # nothing above the field has a column to spend it on. Specs assert the
+      # scrolling through `send`.
+      # 
+      # _@return_ — text column drawn in the field's leftmost cell — the
+      # horizontal scroll offset. Follows {#caret}, always on a glyph boundary.
+      attr_reader left_column: Integer
     end
 
     # A single-line field whose {#value} is a `Float` (or `nil` when empty) —
@@ -4425,12 +5898,9 @@ module Tuile
       # Input fields are focusable by default (overrides {Component#focusable?});
       # 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`).
-      def focusable?: () -> bool
-
-      # _@param_ `event`
-      def handle_mouse: (MouseEvent event) -> void
+      # composing wrappers, so it stays per-class (`DECISIONS.md`
+      # `D_integer_field`).
+      def focusable?: () -> bool
 
       # _@param_ `rect`
       def rect=: (Rect rect) -> void
@@ -4472,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
 
@@ -4488,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:
+    # 
+    #   Component::InfoWindow.open("Help", "A long explanation, wrapped to fit.")
+    #   Component::InfoWindow.open("Files", ["drwx  src/", "-rw-  README.md"])
     # 
-    # Usable tiled (just add to a {Layout}) or as a popup via {.open}, which
-    # wraps it in a {Popup}.
+    # Both write the same body slot — the last writer wins.
     class InfoWindow < Tuile::Component::Window
-      # _@param_ `caption`
+      # _@param_ `caption` — the border title.
+      # 
+      # _@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` — initial content; each entry may contain Rainbow formatting.
-      def initialize: (?String caption, ?::Array[String] lines) -> void
+      # _@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
@@ -4649,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
 
@@ -4691,19 +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 dismisses ({#handle_mouse}); an app
-    #   wanting a key registers a global shortcut and calls {#close}.
+    # - **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
@@ -4726,21 +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
-
-      # Empty: a non-modal popup never owns the status bar, and {Popup}'s
-      # inherited `q Close` hint would be a lie here — no key ever reaches a
-      # notification.
-      def keyboard_hint: () -> String
-
       # 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.
@@ -4752,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
@@ -4761,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
@@ -4874,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
@@ -5080,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
 
@@ -5094,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.
     # 
@@ -5109,9 +6591,10 @@ module Tuile
     #   drop.choose if key == Keys::ENTER            # commit the highlight
     # 
     # It owns only what every such dropdown shares — *placement* included, via
-    # {#anchor_to}. What stays with the driver: the width **policy** ({#anchor_to}
-    # measures nothing itself), filtering, row rendering, the commit action, and
-    # ESC/Enter handling. ESC and Enter carry driver-specific tails (ESC may
+    # {#anchor_to} (below a field) and {#anchor_beside} (beside a parent row, for
+    # a cascading submenu). What stays with the driver: the width **policy**
+    # (neither placement method measures anything itself), filtering, row
+    # rendering, the commit action, and ESC/Enter handling. ESC and Enter carry driver-specific tails (ESC may
     # revert a query; Enter may commit via {#choose} *or* via a separate submit
     # path), so {#move} claims neither — the driver calls {#choose} and {#close}
     # from its own branches.
@@ -5123,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
 
@@ -5141,12 +6624,24 @@ module Tuile
       # _@param_ `proc` — commit callback; see {List#on_item_chosen}.
       def on_item_chosen=: ((Proc | Method)? proc) -> void
 
+      # _@param_ `proc` — highlight-moved callback; see {List#on_cursor_changed}. A cascading driver needs it to drop the panels that belonged to the row the highlight just left.
+      def on_cursor_changed=: ((Proc | Method)? proc) -> void
+
       # _@param_ `cursor` — the highlight; see {List#cursor=}.
       def cursor=: (List::Cursor cursor) -> void
 
       # _@return_ — the list's cursor (the current highlight).
       def cursor: () -> List::Cursor
 
+      # Moves the highlight to the item at `index`, scrolling it into view; see
+      # {List#select}. The positional counterpart of {#move}, for a driver that
+      # picked a row by something other than a key — a mnemonic letter, say.
+      # 
+      # _@param_ `index`
+      # 
+      # _@return_ — whether the highlight moved there.
+      def select: (Integer index) -> bool
+
       # Sizes and places the dropdown against `anchor`: directly beneath it,
       # flipped above when `rows` won't fit below, clamped — with the list
       # scrolling — when neither side has room. Horizontally the left edges line
@@ -5158,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).
       # 
@@ -5172,6 +6675,49 @@ module Tuile
                        ?max_rows: Integer
                      ) -> void
 
+      # Sizes and places the dropdown *beside* `anchor` — the placement a
+      # cascading submenu wants, where {#anchor_to} is the placement a field's
+      # dropdown wants.
+      # 
+      #   sub.anchor_beside(parent.cursor_row_rect, rows: kids.size, width: measured)
+      # 
+      # Horizontally it sits against `anchor`'s right edge, **flipping** to its
+      # left when the right has no room (and clamping to the screen when neither
+      # side does). Vertically it **slides**: the panel's first row lines up with
+      # the anchored row, sliding up only far enough to keep the panel on screen.
+      # 
+      # The two axes are the mirror image of {#anchor_to}'s, for the same reason:
+      # never cover the thing being chosen from. A field's dropdown must not
+      # cover the field, so it flips *vertically* and shares its columns; a
+      # submenu must not cover its parent panel, so it flips *horizontally* and
+      # shares its rows.
+      # 
+      # _@param_ `anchor` — the row the submenu belongs to — typically the parent dropdown's {#cursor_row_rect}. Its width is the parent panel's, which is what the submenu clears.
+      # 
+      # _@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_ `max_rows` — rows shown before the list scrolls.
+      def anchor_beside: (
+                           Rect anchor,
+                           rows: Integer,
+                           width: Integer,
+                           ?max_rows: Integer
+                         ) -> void
+
+      # The highlighted row's rect on screen — what a cascading submenu anchors
+      # against, via {#anchor_beside}.
+      # 
+      # It lives here rather than in the driver because {ListDropdown} owns the
+      # list's geometry: a driver computing `top + position - scroll_top_row`
+      # itself would have to reach through to the private list.
+      # 
+      # _@return_ — one row spanning the panel's width, or `nil` when
+      # the cursor is off-content ({List::Cursor::None}, an empty list) or its
+      # row is scrolled out of the viewport.
+      def cursor_row_rect: () -> Rect?
+
       # Forwards a cursor-movement key to the list. The driver calls this from
       # its own key handler; a truthy return means "consumed — stop here", falsy
       # means "not mine — proceed with normal editing/dispatch". Only {MOVE_KEYS}
@@ -5203,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.
     # 
@@ -5225,8 +6819,6 @@ module Tuile
       # _@param_ `key`
       def handle_key: (String key) -> bool
 
-      def keyboard_hint: () -> String
-
       # Opens a picker as a popup. Picking an option fires `block`, then
       # closes the popup; ESC / `q` close without firing `block`.
       # 
@@ -5395,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
 
@@ -5411,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:
@@ -5585,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
 
@@ -5637,6 +7471,8 @@ module Tuile
     # 
     # - {#preprocess_text} — input filter (e.g. {TextField} truncates to
     #   fit `rect.width - 1`).
+    # - {#preprocess_paste} — the same for {#handle_paste}, which lands a
+    #   whole clipboard at the caret in one mutation.
     # - {#on_text_mutated} / {#on_caret_mutated} — post-mutation side
     #   effects (e.g. {TextArea} invalidates its wrap cache and scrolls to
     #   keep the caret visible).
@@ -5668,6 +7504,34 @@ module Tuile
       # _@param_ `key`
       def handle_key: (String key) -> bool
 
+      # Inserts pasted text at the caret as **one** mutation, so {#on_change}
+      # fires once for the whole paste rather than once per character.
+      # {#preprocess_paste} filters it first.
+      # 
+      # _@param_ `text`
+      # 
+      # _@return_ — always true — a field consumes every paste, an empty
+      # one included.
+      def handle_paste: (String text) -> bool
+
+      # Input filter for {#handle_paste}, the paste-side counterpart of
+      # {#preprocess_text}. Strips the C0 control characters a text buffer
+      # cannot hold — a raw `\e` or `\t` reaching {Buffer} would move the real
+      # terminal cursor mid-frame — keeping `\n`, and turning a tab into a
+      # single space so pasted code keeps its word gaps. {TextField} narrows it
+      # further; an app wanting tab *expansion* overrides {#handle_paste}.
+      # 
+      # _@param_ `text`
+      def preprocess_paste: (String text) -> String
+
+      # Inserts `str` at the caret, leaving the caret behind it. The bulk
+      # counterpart of a subclass's per-key insert.
+      # 
+      # _@param_ `str`
+      # 
+      # _@return_ — true if the text changed.
+      def insert_text: (String str) -> bool
+
       # Renders `text` on the field's background well, looked up from the
       # current {Screen#theme} at paint time: {Theme#active_bg_color} when this
       # input is on the active (focus) chain, {Theme#input_bg_color} otherwise —
@@ -5769,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.
@@ -5877,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.
@@ -5974,6 +7880,28 @@ module Tuile
       attr_reader key: String
     end
 
+    # Text arrived from the clipboard rather than the keyboard: the terminal
+    # bracketed it in {Keys::PASTE_START} … {Keys::PASTE_END} because
+    # {Screen#run_event_loop} enabled mode 2004. The whole paste is one event,
+    # so a component sees one mutation instead of a keystroke per character —
+    # and a pasted line break can no longer be mistaken for a typed Enter.
+    # 
+    # {Screen#event_loop} routes it to {Component#handle_paste} down the focus
+    # chain. It never enters the key ladder: no Tab traversal, no global
+    # shortcut, no {Component#handle_key}.
+    # 
+    # @!attribute [r] text
+    #   @return [String] the pasted text, `\n`-normalized by
+    #     {Keys.normalize_paste}.
+    class PasteEvent
+      # _@param_ `text`
+      def initialize: (text: String) -> void
+
+      # _@return_ — the pasted text, `\n`-normalized by
+      # {Keys.normalize_paste}.
+      attr_reader text: String
+    end
+
     # An error event, causes {EventQueue#run_loop} to throw `StandardError` with
     # {#error} as its origin.
     # 
@@ -6032,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.
@@ -6110,15 +8058,52 @@ module Tuile
     # _@param_ `str`
     def emit: (String str) -> void
 
+    # Pastes `text` into the focused component, as a real terminal would with
+    # bracketed paste on:
+    # 
+    #   area.focus
+    #   Screen.instance.paste("one\r\ntwo")
+    #   area.text   # => "one\ntwo" — one mutation, no ENTER anywhere
+    # 
+    # Goes through {Keys.normalize_paste} first, so a spec can hand it the
+    # CR-flavored line endings terminals actually deliver and still assert
+    # against `\n`.
+    # 
+    # _@param_ `text`
+    # 
+    # _@return_ — true if some component consumed it.
+    def paste: (String text) -> bool
+
     # _@param_ `component` — the component to check.
     def invalidated?: (Component component) -> bool
 
     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
@@ -6184,33 +8169,40 @@ module Tuile
   # 
   # {Screen} is a singleton runtime owner (event loop, lock, terminal IO,
   # invalidation set). All actual UI lives under a {ScreenPane}: the tiled
-  # {#content}, the modal {#popups} stack, and the bottom {#status_bar}.
-  # Putting them under a single Component parent gives focus traversal a real
-  # root, makes {Component#attached?} a one-liner, and lets popup-focus repair
-  # fall out of the standard {Component#on_child_removed} hook.
+  # {#content} and the {#popups} stack. Putting them under a single Component
+  # parent gives focus traversal a real root, makes {Component#attached?} a
+  # one-liner, and lets popup-focus repair fall out of the standard
+  # {Component#on_child_removed} hook.
+  # 
+  # 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`).
   # 
   # 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
@@ -6235,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
-    # owner": the popup that scopes key dispatch, blocks mouse clicks, owns
-    # the status bar, and confines Tab cycling. Non-modal overlays are
-    # excluded — they float above the content without capturing input.
+    # _@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. 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.
@@ -6247,11 +8239,11 @@ module Tuile
     # _@param_ `new_rect`
     def rect=: (Rect new_rect) -> void
 
-    # Lays out content (full pane minus the bottom row) and the status bar
-    # (bottom row). Each popup re-resolves its {Component::Popup#size} against
-    # the new screen via {Component::Popup#reposition} — so a {Fraction} size
-    # tracks resize — repositioning itself (modal popups recenter; non-modal
-    # overlays keep the top-left their owner assigned).
+    # Gives {#content} the whole pane rect — the pane reserves nothing for
+    # 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).
     def layout: () -> void
 
     # Pane paints nothing itself; its children paint over the entire rect.
@@ -6278,6 +8270,15 @@ module Tuile
     # _@return_ — true if the key was handled.
     def handle_key: (String key) -> bool
 
+    # Delivers pasted text along the same focus chain {#handle_key} bubbles
+    # along, and with the same scoping — first {Component#handle_paste}
+    # returning true wins.
+    # 
+    # _@param_ `text`
+    # 
+    # _@return_ — true if the text was consumed.
+    def handle_paste: (String text) -> bool
+
     # Mouse events check popups in reverse stacking order (topmost first), and
     # fall through to content only when no popup is hit *and* no modal popup is
     # open. This preserves modal click-blocking — an open modal eats clicks
@@ -6285,6 +8286,35 @@ module Tuile
     # inside it route to it (e.g. click-to-select), clicks elsewhere reach the
     # content beneath.
     # 
+    # A left click also *dismisses* the open popups it landed outside of that
+    # 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::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
+    # field opened, and a menu cascade being dismissed by a click on one of its
+    # own deeper panels. Order carries no meaning here — between unrelated
+    # overlays it is merely the order they opened in — so ownership is declared
+    # rather than inferred from the stack.
+    # 
+    # Two halves of the ordering are load-bearing, and both are specced:
+    # 
+    # - **Snapshot before routing.** A popup the delivered click *opens* must
+    #   not be in the set (it would immediately dismiss itself — every
+    #   {Component::Select} would be unopenable by mouse).
+    # - **Close after routing.** A widget toggling its own overlay from a click
+    #   on its face closes it during delivery, and {Component::Popup#close} is
+    #   idempotent, so the dismissal no-ops. Close *first* and the widget sees
+    #   a shut overlay and reopens it — a Select's dropdown could then never be
+    #   dismissed by clicking the Select.
+    # 
+    # The snapshot is a fresh array for a third reason: a handler may close
+    # further popups, and `@popups` must not be mutated mid-iteration.
+    # 
     # _@param_ `event`
     def handle_mouse: (MouseEvent event) -> void
 
@@ -6303,6 +8333,23 @@ module Tuile
     # _@param_ `child`
     def on_child_removed: (Component child) -> void
 
+    # 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 overlay the click landed in, if any.
+    def kept_by: (Component::Overlay? hit) -> ::Array[Component::Overlay]
+
+    # _@param_ `component`
+    # 
+    # _@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
     # — when focus is nil or sits outside `scope`; the latter is what makes an
@@ -6316,6 +8363,14 @@ module Tuile
     # _@return_ — true if some component on the chain handled the key.
     def bubble_key: (String key, Component scope) -> bool
 
+    # {Screen#focused} and its ancestors up to and including `scope`.
+    # 
+    # _@param_ `scope` — the modal scope root (topmost popup or content).
+    # 
+    # _@return_ — the chain, innermost first; nil when
+    # focus is nil or sits outside `scope`.
+    def focus_chain: (Component scope) -> ::Array[Component]?
+
     # First {Component#tab_stop?} in `root`'s subtree (pre-order), falling
     # back to `root` itself when the subtree has no tab stops. Returns `nil`
     # if `root` is `nil`.
@@ -6326,18 +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 bottom status bar.
-    attr_reader status_bar: Component::Label
+    # _@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
@@ -6368,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
@@ -6503,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
 
@@ -6514,6 +8571,54 @@ module Tuile
     # _@param_ `fg` — foreground color, coerced via {Color.coerce}. `nil` clears fg back to the terminal default.
     def with_fg: ((Color | Symbol | Integer | ::Array[Integer])? fg) -> StyledString
 
+    # Returns a new {StyledString} with `bold` applied to every span, preserving
+    # each span's text and other style attributes (`fg`, `bg`, `italic`,
+    # `underline`, `strikethrough`). The bold-attribute counterpart of
+    # {#with_bg} / {#with_fg}: it emphasizes a whole run of app-authored,
+    # possibly multi-span content — a widget marking one caption out of several
+    # as selected, where the caption may already carry its own colors.
+    # 
+    # There is deliberately no `under_bold` (the fill-unset counterpart
+    # {#under_bg} provides for backgrounds): a background is inherited down the
+    # component tree, so a span with none has a meaningful "unset" state to
+    # fill, while `bold` is a plain per-span attribute that is either on or
+    # off. Pass `bold: false` to clear it.
+    # 
+    # _@param_ `bold` — whether the spans should be bold.
+    def with_bold: (?bold: bool) -> StyledString
+
+    # Returns a new {StyledString} with `underline` applied to every span,
+    # preserving each span's text and other style attributes (`fg`, `bg`,
+    # `bold`, `italic`, `strikethrough`). Slice and rejoin to underline *part*
+    # of a string, which is what a one-character cue needs:
+    # 
+    #   cap = StyledString.parse("File")
+    #   cap.slice(0, 1).with_underline + cap.slice(1, cap.display_width - 1)
+    #   # => "File" with the F underlined — a menu mnemonic
+    # 
+    # Note {#slice} counts **columns**, not characters, so a caption with a
+    # wide glyph before the cue needs the prefix measured rather than counted.
+    # 
+    # There is deliberately no `under_underline`, for the reason {#with_bold}
+    # spells out. Pass `underline: false` to clear it.
+    # 
+    # _@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
@@ -6607,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
 
@@ -6621,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
@@ -6665,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
@@ -6823,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:
   # 
@@ -6837,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
@@ -6854,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).
@@ -6862,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?
 
-    # 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.
+    # 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 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
@@ -6891,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
@@ -6906,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.