tuile 0.12.0 → 0.13.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.
@@ -879,10 +921,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#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
   # 
@@ -957,22 +1004,6 @@ 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.
     # 
@@ -988,7 +1019,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 +1054,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,9 +1069,6 @@ 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
     # from {#pane}, repairs focus, and repaints the scene.
     # 
@@ -1090,6 +1116,22 @@ module Tuile
     # _@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});
@@ -1173,6 +1215,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.
@@ -1231,8 +1286,33 @@ module Tuile
     # _@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 +1320,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
 
@@ -1301,14 +1378,24 @@ 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.
+    # 
+    # **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,6 +1409,27 @@ module Tuile
     # _@return_ — true if the key was handled, false if not.
     def handle_key: (String _key) -> bool
 
+    # 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
+
     # Handles mouse event. Default implementation focuses this component when
     # clicked (if {#focusable?}).
     # 
@@ -1399,15 +1507,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.
     # 
@@ -1696,6 +1799,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 +2156,319 @@ module Tuile
       end
     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: () -> Rect
+
+      # 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
@@ -2123,6 +2555,10 @@ module Tuile
     # 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.
+    # 
+    # A left click *outside* the popup closes it too, modal or not — see
+    # {#close_on_outside_click?} for the exact contract and {#on_close=} for
+    # the notice a driver hears when it happens.
     class Popup < Component
       include Tuile::Component::HasContent
 
@@ -2131,11 +2567,41 @@ module Tuile
       # _@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_ `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 {#close_on_outside_click?}.
+      def initialize: (
+                        ?content: Component?,
+                        ?modal: bool,
+                        ?size: (Size | Fraction),
+                        ?close_on_outside_click: bool
+                      ) -> void
 
       # _@return_ — whether this popup is modal. See {#initialize}.
       def modal?: () -> bool
 
+      # Whether a left click outside this popup closes it (default true, modal or
+      # not). The pane does the closing — {ScreenPane#handle_mouse} snapshots
+      # the open popups *before* routing the click and closes the dismissable
+      # ones *after*, so a widget that toggles its own overlay from a click on
+      # its face (a {Component::Select}, a {Component::MenuBar} title) still
+      # toggles correctly: the delivered click closes the overlay and the
+      # dismissal then no-ops on it, rather than closing and reopening it. Only
+      # `:left` dismisses; scroll and right clicks never do.
+      # 
+      # **"Outside" spans the {#owner} chain, not just this rect.** A click
+      # counts as inside this popup when it lands in its rect *or* in any popup
+      # that belongs to it — so a dialog is not dismissed by a click on a
+      # dropdown its own field opened, and a menu cascade is not dismissed by a
+      # click on one of its deeper panels. Popups with no owner relationship are
+      # independent: clicking one dismisses the other, which is what a
+      # window-like overlay should do. A popup that must survive unrelated
+      # clicks entirely ({Component::Notification}) sets this false.
+      # 
+      # Every dismissable popup closes, not just the topmost, and stacking order
+      # plays no part: a {Component::MenuBar} cascade must vanish whole on one
+      # click on the background, not peel one panel per click.
+      def close_on_outside_click?: () -> bool
+
       def focusable?: () -> bool
 
       # Reassigns the popup's rect, escalating to a full scene repaint when an
@@ -2181,9 +2647,6 @@ module Tuile
       # 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,6 +2656,10 @@ module Tuile
       # _@return_ — true if the key was handled.
       def handle_key: (String key) -> bool
 
+      # Fires {#on_close}. A subclass overriding this **must** call `super`, or
+      # the popup's driver never hears that it closed.
+      def on_detached: () -> void
+
       # Content fills the popup's full rect — Popup has no border to subtract.
       # 
       # _@param_ `content`
@@ -2205,6 +2672,37 @@ module Tuile
 
       # _@return_ — the popup's declared size. See {#size=}.
       attr_accessor size: (Size | Fraction)
+
+      # _@return_ — see {#close_on_outside_click?}.
+      attr_writer close_on_outside_click: bool
+
+      # The component this overlay is *part of*, or `nil` (the default) when it
+      # is an overlay in its own right. It exists for outside-click dismissal:
+      # a click inside this popup also counts as inside whatever popup encloses
+      # its owner, so the host is not dismissed by a click on a panel it put
+      # there. See {#close_on_outside_click?}.
+      # 
+      # Set it to the *driver* — {Component::ComboBox} hands its dropdown
+      # `self` — rather than to the enclosing popup: the driver knows what it
+      # is, while the popup above it is a tree relationship the pane resolves
+      # at click time (so it cannot go stale). Any {Component} is accepted, and
+      # a `Popup` resolves to itself, which is how a
+      # {Component::MenuBar::Cascade} chains each panel to the one it dropped
+      # out of.
+      attr_accessor owner: Component?
+
+      # A callback taking no arguments, fired once this popup has left the
+      # screen — **however it left**: {#close}, a direct {Screen#remove_popup},
+      # an outside click, or teardown via {Screen#close}. That unconditionality
+      # is the point, so it hangs off {#on_detached} rather than {#close}; a
+      # driver keeping its own record of open popups reconciles it here and
+      # cannot drift ({Component::MenuBar::Cascade} is the worked example).
+      # 
+      # It fires *after* the popup is detached, so {#open?} is already false and
+      # the usual {Component#on_detached} caveats apply: release state, don't
+      # inspect the tree, keep it trivial (it may run while the pane is mid-way
+      # through closing a batch of popups, and a raise propagates).
+      attr_accessor on_close: Proc?
     end
 
     # A clickable button. Activated by Enter, Space, or a left mouse click;
@@ -2765,8 +3263,6 @@ module Tuile
 
       def tab_stop?: () -> bool
 
-      def keyboard_hint: () -> String
-
       # Re-anchors the (open) dropdown after a move or resize.
       # 
       # _@param_ `new_rect`
@@ -3097,6 +3593,495 @@ module Tuile
       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: () -> Rect
+
+      # _@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
@@ -3144,8 +4129,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}.
       # 
@@ -3312,6 +4295,164 @@ 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
+
+      # Forwards to whichever child the click landed on — the strip's row, or
+      # the pane below it.
+      # 
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
+
+      # Sends focus to the strip: a sheet is a container, and the strip is where
+      # a tab switch is driven from. The pane is a Tab press away.
+      def on_focus: () -> void
+
+      # 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 +4468,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 +4898,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 +4912,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
 
@@ -4188,8 +5337,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 +5372,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 +5447,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 +5469,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) —
@@ -4697,8 +5859,11 @@ module Tuile
     # 
     # - **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}.
+    #   `q`/ESC arrives here. A left click *on the box* dismisses
+    #   ({#handle_mouse}); an app wanting a key registers a global shortcut and
+    #   calls {#close}. A click *elsewhere* does not — this is the one popup
+    #   with {Popup#close_on_outside_click?} false, since a toast is timed and
+    #   an unrelated click is not about it.
     # - **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.
@@ -4736,11 +5901,6 @@ module Tuile
       # _@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.
@@ -5109,9 +6269,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.
@@ -5141,12 +6302,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
@@ -5172,6 +6345,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}
@@ -5225,8 +6441,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`.
       # 
@@ -5637,6 +6851,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 +6884,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 —
@@ -5974,6 +7218,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.
     # 
@@ -6110,6 +7376,22 @@ 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
 
@@ -6184,10 +7466,15 @@ 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
@@ -6237,9 +7524,9 @@ module Tuile
 
     # _@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.
+    # owner": the popup that scopes key dispatch, blocks mouse clicks, and
+    # confines Tab cycling. Non-modal overlays are excluded — they float above
+    # the content without capturing input.
     def modal_popup: () -> Component::Popup?
 
     # Re-lays out children whenever the pane's own rect changes.
@@ -6247,11 +7534,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#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 +7565,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 +7581,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::Popup#close_on_outside_click?}). That is a
+    # second thing happening on a click, but not a second dispatch: the click is
+    # still delivered exactly once, down one chain, and a dismissed popup is
+    # closed rather than told.
+    # 
+    # "Outside" is measured against the {Component::Popup#owner} chain, not
+    # 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 +7628,22 @@ module Tuile
     # _@param_ `child`
     def on_child_removed: (Component child) -> void
 
+    # The popups a click counts as landing *inside*: the one it hit, plus every
+    # popup that one belongs to, up the {Component::Popup#owner} chain. An owner
+    # is any component, so it is resolved to the popup enclosing it (a popup
+    # resolves to itself) — which keeps the relationship a live tree question
+    # rather than one frozen when the overlay opened. The `include?` guard makes
+    # a mis-wired cycle terminate instead of hanging the UI thread.
+    # 
+    # _@param_ `hit` — the popup the click landed in, if any.
+    def kept_by: (Component::Popup? hit) -> ::Array[Component::Popup]
+
+    # _@param_ `component`
+    # 
+    # _@return_ — `component` itself when it is a popup,
+    # else the nearest popup above it, else nil.
+    def enclosing_popup: (Component? component) -> Component::Popup?
+
     # 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 +7657,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`.
@@ -6330,9 +7679,6 @@ module Tuile
     # 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
   end
 
   # An immutable string-with-styling, modeled as a sequence of {Span}s where
@@ -6514,6 +7860,40 @@ 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
+
     def inspect: () -> String
 
     def build_ansi: () -> String