tuile 0.11.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.
@@ -550,7 +592,7 @@ module Tuile
 
   # An in-memory grid of styled cells mirroring the terminal screen. This is
   # the back buffer behind flicker-free rendering: components paint into it
-  # (via {#set_line} / {#set_char} / {#fill}) instead of writing escape
+  # (via {#set_text} / {#set_char} / {#fill}) instead of writing escape
   # sequences straight to the terminal, and {#flush} emits the minimal escape
   # string needed to bring a terminal — one that already matches the buffer's
   # state as of the previous flush — up to date. Only cells that actually
@@ -603,7 +645,7 @@ module Tuile
     # _@param_ `y` — row.
     # 
     # _@return_ — the live cell at `(x, y)` (do not mutate — paint via
-    # {#set_char} / {#set_line} so dirty tracking stays correct), or nil when
+    # {#set_char} / {#set_text} so dirty tracking stays correct), or nil when
     # out of bounds.
     def cell: (Integer x, Integer y) -> Cell?
 
@@ -632,14 +674,14 @@ module Tuile
 
     # Writes a {StyledString} starting at `(x, y)`, advancing by each grapheme's
     # display width and clipping at the right edge. Newlines are not handled —
-    # pass one physical line.
+    # pass the text of one row.
     # 
     # _@param_ `x` — starting column.
     # 
     # _@param_ `y` — row.
     # 
     # _@param_ `styled`
-    def set_line: (Integer x, Integer y, StyledString styled) -> void
+    def set_text: (Integer x, Integer y, StyledString styled) -> void
 
     # Fills the intersection of `rect` and the buffer with blank cells in
     # `style` — the cell-grid equivalent of clearing a background. Only `bg`
@@ -695,7 +737,7 @@ module Tuile
     # 
     # _@return_ — row `y` rendered to ANSI across its full width — the
     # minimal-SGR encoding of its cells, equivalent to what a component's
-    # `set_line` of the whole row would have printed. Intended for tests that
+    # `set_text` of the whole row would have printed. Intended for tests that
     # assert on styled output (see {FakeScreen}); empty for an out-of-range row.
     def row_ansi: (Integer y) -> String
 
@@ -709,13 +751,13 @@ module Tuile
     # _@param_ `rect`
     # 
     # _@return_ — each row within `rect` rendered to ANSI, top to
-    # bottom — byte-identical to what a component's per-row `set_line` over
+    # bottom — byte-identical to what a component's per-row `set_text` over
     # that rect emitted. The region equivalent of {#row_ansi}. Intended for
     # tests asserting styled output.
     def region_ansi: (Rect rect) -> ::Array[String]
 
     # Core of {#set_char} with the grapheme's display width already known.
-    # {#set_line} computes each width once while advancing the column and passes
+    # {#set_text} computes each width once while advancing the column and passes
     # it straight through, so the paint hot path measures every grapheme exactly
     # once (and that once is a {.display_width} memo read). See {#set_char} for
     # the wide-glyph / clipping / out-of-bounds contract.
@@ -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.
@@ -1182,7 +1237,7 @@ module Tuile
     attr_reader color_scheme: Symbol
 
     # _@return_ — the back buffer components paint into
-    # ({Buffer#set_line} / {Buffer#fill} / {Buffer#set_char}).
+    # ({Buffer#set_text} / {Buffer#fill} / {Buffer#set_char}).
     attr_reader buffer: Buffer
 
     # Handler invoked when a {StandardError} escapes an event handler inside
@@ -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.
     # 
@@ -1517,7 +1620,7 @@ module Tuile
     # _@param_ `area` — the region to blank; defaults to the whole {#rect}.
     def clear_background: (?Rect area) -> void
 
-    # {Buffer#set_line} wrapper that fills {#effective_bg_color} behind any span
+    # {Buffer#set_text} wrapper that fills {#effective_bg_color} behind any span
     # with no bg of its own (via {StyledString#under_bg}), so an inherited
     # {#bg_color} shows through the content a component paints. A no-op layer
     # when nothing is inherited. Self-painters (those skipping the {#repaint}
@@ -1528,9 +1631,9 @@ module Tuile
     # _@param_ `y` — row.
     # 
     # _@param_ `styled`
-    def draw_line: (Integer x, Integer y, StyledString styled) -> void
+    def draw_text: (Integer x, Integer y, StyledString styled) -> void
 
-    # {#draw_line}'s single-grapheme counterpart: writes `grapheme` at `(x, y)`,
+    # {#draw_text}'s single-grapheme counterpart: writes `grapheme` at `(x, y)`,
     # filling {#effective_bg_color} when `style` carries no bg of its own.
     # 
     # _@param_ `x` — column.
@@ -1576,7 +1679,7 @@ module Tuile
     # Called on every attached component (pre-order, popups included) when
     # {Screen#theme} changes — at {Screen#theme=} / {Screen#theme_def=} and on
     # OS appearance flips. The hook exists for app *content* whose colors were
-    # baked in from the old theme (a {Label#text} / {List#lines} {StyledString}
+    # baked in from the old theme (a {Label#text} / {List#lines=} {StyledString}
     # styled with `theme[:accent]`); rebuild it here by re-running the code that
     # rendered it. See book ch6 for why built-in accents need no such handling.
     # 
@@ -1586,62 +1689,84 @@ module Tuile
     # {#on_theme_changed=} listener keeps firing.
     attr_accessor on_theme_changed: Proc?
 
-    # A scrollable list of items with cursor support.
+    # A scrollable list of typed items, one row each, with cursor support.
+    # 
+    #   list = Component::List.new
+    #   list.items    = people
+    #   list.renderer = ->(p) { StyledString.plain(p.name) + screen.theme.hint(" #{p.email}") }
+    #   list.cursor   = List::Cursor.new                  # a bare list has none
+    #   list.on_item_chosen = ->(index, person) { open(person) }
     # 
-    # Items are modeled as {StyledString}s and painted directly into the
-    # component's {#rect}. Lines wider than the viewport are ellipsized via
-    # {StyledString#ellipsize} with span styles preserved across the cut.
-    # Vertical scrolling is via {#top_line}; enable {#auto_scroll} to keep the
-    # bottom in view.
+    # The {#renderer} turns an item into one row; the default renders an item
+    # as itself, so a list of `String`s or {StyledString}s needs none — which
+    # is what {#lines=} and {#build_lines} are, items that are their own
+    # rendering (split on `\n`, one row per line).
     # 
-    # Cursor is supported; call {#cursor=} to change cursor behavior. The
-    # cursor responds to arrows, `jk`, Home/End, Ctrl+U/D and scrolls the
-    # list automatically. The cursor highlight overlays
-    # {Theme#active_bg_color} while preserving each span's foreground color.
+    # There are no appenders. The items are always assigned whole — an app that
+    # grows a list keeps its own array and re-assigns it (`list.items = mine`) —
+    # so a `List` stays a *snapshot of a collection*, which is the only shape a
+    # lazily-sourced provider could ever fill.
+    # 
+    # Rows wider than the viewport are ellipsized via {StyledString#ellipsize}
+    # with span styles preserved across the cut. Vertical scrolling is via
+    # {#scroll_top_row}; enable {#auto_scroll} to keep the bottom in view. The cursor
+    # responds to arrows, `jk`, Home/End, Ctrl+U/D and scrolls the list
+    # automatically; its highlight overlays {Theme#active_bg_color} while
+    # preserving each span's foreground color.
+    # 
+    # == Implementation details
+    # Rendering is lazy: only the rows in the viewport are rendered, each
+    # memoized until {#items=}, {#renderer=} or a width change drops the cache.
+    # So a renderer runs *at paint time*, on any frame — keep it pure and
+    # cheap; work that reaches a service belongs in the item, not in the
+    # renderer. {#select_next} deliberately renders without memoizing: one
+    # failed scan would otherwise cache a row per item.
     class List < Component
+      DEFAULT_RENDERER: Proc
+
       def initialize: () -> void
 
       # _@return_ — whether {#auto_scroll} is currently tailing. True
-      # while the viewport sits at the last line; flips to false the moment
+      # while the viewport sits at the last row; flips to false the moment
       # the user scrolls up, and back to true once they scroll to the bottom
       # again. Only consulted when {#auto_scroll} is enabled.
       def following?: () -> bool
 
-      # Sets new lines. Each entry is coerced into a {StyledString} (a
-      # `String` is parsed via {StyledString.parse}, so embedded ANSI is
-      # honored; a {StyledString} is used as-is; anything else is stringified
-      # via `#to_s` first), then split on `\n` into separate lines via
-      # {StyledString#lines}, with trailing empty pieces dropped and trailing
-      # ASCII whitespace stripped — symmetric with {#add_lines}, so the
-      # stored `@lines` is always `Array<StyledString>`.
+      # Re-renders every row — for a {#renderer} whose *inputs* changed while
+      # it and {#items} stayed the same, e.g. one prefixing a marker read from
+      # a selection it closes over:
+      # 
+      #   def value=(new_value)   # RadioGroup: the marked row moved
+      #     super
+      #     content.refresh_rows
+      #   end
+      def refresh_rows: () -> void
+
+      # Sets the items from line-flavored input: each entry is coerced into a
+      # {StyledString} (a `String` is parsed via {StyledString.parse}, so
+      # embedded ANSI is honored; a {StyledString} is used as-is; anything else
+      # is stringified via `#to_s` first), then split on `\n` into separate
+      # lines via {StyledString#lines}, with trailing empty pieces dropped and
+      # trailing ASCII whitespace stripped. The resulting {StyledString}s
+      # *are* the {#items}, so under the
+      # {DEFAULT_RENDERER} each is its own row.
       # 
       # _@param_ `lines` — entries are `String`, `StyledString`, or anything that responds to `#to_s`.
       def lines=: (::Array[untyped] lines) -> void
 
-      # Without a block, returns the current lines. With a block, fully
-      # re-populates the list:
+      # Fully re-populates the list, line-flavored: yields a fresh buffer and
+      # assigns it through {#lines=}, so each entry is coerced, split and
+      # rstripped exactly as there. The buffer is a plain `Array`, which a
+      # builder can read mid-build — recording the row a {Cursor::Limited} may
+      # land on is the case this exists for:
       # ```ruby
-      # list.lines do |buffer|
-      #   buffer << "Hello!"
+      # list.build_lines do |lines|
+      #   cursor_positions << lines.size
+      #   lines << format_overview(vm)
+      #   lines << format_detail(vm)
       # end
       # ```
-      # 
-      # _@return_ — current lines (when called without a
-      # block).
-      def lines: () ?{ (::Array[untyped] buffer) -> void } -> ::Array[StyledString]
-
-      # sord duck - #to_s looks like a duck type with an equivalent RBS interface, replacing with _ToS
-      # Adds a line.
-      # 
-      # _@param_ `line`
-      def add_line: ((String | StyledString | _ToS) line) -> void
-
-      # Appends given lines. Each entry is parsed the same way as in
-      # {#lines=}: coerced to a {StyledString}, split on `\n`, with trailing
-      # empty pieces dropped and trailing ASCII whitespace stripped.
-      # 
-      # _@param_ `lines` — entries are `String`, `StyledString`, or anything that responds to `#to_s`.
-      def add_lines: (::Array[untyped] lines) -> void
+      def build_lines: () ?{ (::Array[untyped] buffer) -> void } -> void
 
       def focusable?: () -> bool
 
@@ -1652,15 +1777,15 @@ module Tuile
       # _@return_ — true if the key was handled.
       def handle_key: (String key) -> bool
 
-      # Moves the cursor to the next line whose text contains `query`
+      # Moves the cursor to the next item whose text contains `query`
       # (case-insensitive substring match). Search wraps around the end of the
-      # list. Only lines reachable by the current {#cursor} are considered.
-      # Matching uses the line's plain text — span styles do not affect the
+      # list. Only items reachable by the current {#cursor} are considered.
+      # Matching uses the rendered row's plain text — span styles do not affect the
       # match.
       # 
       # _@param_ `query` — substring to match. Empty query never matches.
       # 
-      # _@param_ `include_current` — when true, the current cursor position is eligible (useful when the query has just changed and the current line may still match); when false, the search starts after the current position (useful for "find next" key bindings that should advance past the current).
+      # _@param_ `include_current` — when true, the current cursor position is eligible (useful when the query has just changed and the current item may still match); when false, the search starts after the current position (useful for "find next" key bindings that should advance past the current).
       # 
       # _@return_ — true if a match was found.
       def select_next: (String query, ?include_current: bool) -> bool
@@ -1674,25 +1799,42 @@ 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
 
-      # Paints the list items into {#rect}.
+      # Paints the visible items into {#rect}, rendering the ones not already
+      # cached.
       # 
       # Skips the {Component#repaint} default's auto-clear: every row of
       # {#rect} is painted below (with blank padding past the last item),
       # so the parent contract — "fully draw over your rect" — is met
-      # without an upfront wipe. Rows go through {Component#draw_line}, so
+      # without an upfront wipe. Rows go through {Component#draw_text}, so
       # content *and* blank filler inherit {Component#effective_bg_color}
       # (a {#bg_color} set here or on an ancestor); the cursor row's
       # {Theme#active_bg_color} highlight composes on top of it.
       def repaint: () -> void
 
-      # Rebuilds pre-padded lines when the wrap width changes. The wrap width
-      # depends on {#rect}`.width` and the scrollbar gutter, both of which
-      # trigger this hook. Also re-evaluates {#auto_scroll}: if items were
-      # appended while the rect was empty (e.g. a {Popup}-wrapped list got
-      # `add_line` calls before the popup was opened), the auto-scroll update
+      # Drops the rendered-row cache when the wrap width changes. The wrap
+      # width depends on {#rect}`.width` and the scrollbar gutter, both of
+      # which trigger this hook. Also re-evaluates {#auto_scroll}: if items were
+      # assigned while the rect was empty (e.g. a {Popup}-wrapped list was
+      # populated before the popup was opened), the auto-scroll update
       # was skipped because there was no viewport — re-run it now that there
       # is one, so the list snaps to the bottom on first paint.
       def on_width_changed: () -> void
@@ -1702,7 +1844,7 @@ module Tuile
       # via {StyledString.parse}, StyledString passed through, anything else
       # via `#to_s`), then split on `\n` via {StyledString#lines} — with
       # trailing empty pieces dropped (matching `String#split("\n")`'s
-      # default behavior, so `add_line ""` is a no-op) — and trailing ASCII
+      # default behavior, so a lone `""` entry adds no row) — and trailing ASCII
       # whitespace stripped on each resulting line.
       # 
       # _@param_ `entries`
@@ -1719,16 +1861,16 @@ module Tuile
       # _@param_ `line`
       def rstrip_styled: (StyledString line) -> StyledString
 
-      # _@return_ — true if the cursor sits on a real content line.
+      # _@return_ — true if the cursor sits on a real item.
       def cursor_on_item?: () -> bool
 
-      # Calls {#on_item_chosen} with the cursor's current `(index, line)`.
+      # Calls {#on_item_chosen} with the cursor's current `(index, item)`.
       # Caller must ensure {#cursor_on_item?}.
       def fire_item_chosen: () -> void
 
-      # _@return_ — `[position, line_at_position]`, with `line` nil when the cursor is
+      # _@return_ — `[position, item_at_position]`, with the item nil when the cursor is
       # off-content.
-      def cursor_state: () -> [[Integer, StyledString, NilClass]]
+      def cursor_state: () -> [[Integer, Object, NilClass]]
 
       # Fires {#on_cursor_changed} if {#cursor_state} differs from the last
       # fired state. Idempotent — safe to call after any mutation.
@@ -1762,97 +1904,115 @@ module Tuile
       # Scrolls the viewport so the cursor is visible.
       def move_viewport_to_cursor: () -> void
 
-      # _@return_ — the max value of {#top_line}.
-      def top_line_max: () -> Integer
+      # _@return_ — the max value of {#scroll_top_row}.
+      def scroll_top_row_max: () -> Integer
 
-      # _@return_ — whether the viewport is pinned to the last line.
-      # Drives {#following?}: re-evaluated on every {#top_line=}.
+      # _@return_ — whether the viewport is pinned to the last row.
+      # Drives {#following?}: re-evaluated on every {#scroll_top_row=}.
       def at_bottom?: () -> bool
 
-      # _@return_ — the number of visible lines.
-      def viewport_lines: () -> Integer
+      # _@return_ — the number of visible rows.
+      def viewport_rows: () -> Integer
 
       # Scrolls the list.
       # 
       # _@param_ `delta` — negative scrolls up, positive scrolls down.
-      def move_top_line_by: (Integer delta) -> void
+      def move_scroll_top_row_by: (Integer delta) -> void
 
-      # If auto-scrolling, recalculate the top line and snap the cursor to the
+      # If auto-scrolling, recalculate the top row and snap the cursor to the
       # last reachable position. Without the cursor snap the viewport gets
       # yanked back to wherever the cursor sat on the next arrow press,
       # negating the auto-scroll. Skipped when {#rect} is empty: without a
-      # viewport the "lines minus viewport" formula yields `@lines.size`,
-      # which would leave `top_line` past the last item once a real rect
+      # viewport the "items minus viewport" formula yields `@items.size`,
+      # which would leave `scroll_top_row` past the last item once a real rect
       # arrives. {#on_width_changed} re-runs this hook when the rect grows so
       # the snap-to-bottom intent is preserved.
       # 
       # Gated on {#following?}: once the user scrolls up off the bottom the
       # cursor snap and viewport pin are both skipped, so reading older
-      # content is not interrupted by incoming lines. {#top_line=} re-arms
+      # content is not interrupted by incoming items. {#scroll_top_row=} re-arms
       # `@follow` when the viewport returns to the bottom.
-      def update_top_line_if_auto_scroll: () -> void
+      def update_scroll_top_row_if_auto_scroll: () -> void
 
       # _@return_ — whether the scrollbar should be drawn right now.
       def scrollbar_visible?: () -> bool
 
-      # _@return_ — column width available for line content (rect width
+      # _@return_ — column width available for row content (rect width
       # minus the scrollbar gutter, when visible). `0` when {#rect}'s width
       # is non-positive.
       def content_width: () -> Integer
 
-      # Recomputes {@padded_lines} for the current rect width and scrollbar
-      # visibility. Each line is ellipsized to fit and pre-padded with
-      # single-space gutters on each side, so {#paintable_line} only has to
-      # apply the cursor highlight (if any) and append the scrollbar glyph.
-      def rebuild_padded_lines: () -> void
+      # Discards every rendered row, so the next paint re-renders the viewport
+      # against the current items, renderer and width.
+      def drop_row_cache: () -> void
+
+      # _@param_ `index` — 0-based index into {#items}.
+      # 
+      # _@return_ — the item's padded row, rendered on first use and
+      # memoized until {#drop_row_cache}.
+      def padded_row: (Integer index) -> StyledString
+
+      # _@return_ — the blank row painted past the last item.
+      def blank_row: () -> StyledString
+
+      # Renders one item, *without* populating the row cache — {#search_and_go}
+      # scans with this, and caching a failed scan would grow the cache to one
+      # row per item.
+      # 
+      # _@param_ `item`
+      # 
+      # _@return_ — one row: the {#renderer}'s output coerced to a
+      # {StyledString}, cut to its first line since a `\n` reaching the buffer
+      # would corrupt the frame.
+      def render: (Object item) -> StyledString
 
-      # Pads `line` to one full row of the viewport (scrollbar gutter
-      # excluded). Lines wider than the content area are ellipsized via
+      # Pads `row` to one full row of the viewport (scrollbar gutter
+      # excluded). Rows wider than the content area are ellipsized via
       # {StyledString#ellipsize} (span styles survive the cut); shorter
-      # lines are padded with default-styled spaces.
+      # ones are padded with default-styled spaces.
       # 
-      # _@param_ `line`
+      # _@param_ `row`
       # 
       # _@return_ — exactly {#content_width} display columns wide
       # (or {StyledString::EMPTY} when content_width is non-positive).
-      def pad_to_row: (StyledString line) -> StyledString
+      def pad_to_row: (StyledString row) -> StyledString
 
-      # _@param_ `index` — 0-based index into {#lines}.
+      # _@param_ `index` — 0-based index into {#items}.
       # 
       # _@param_ `row_in_viewport` — 0-based row within the viewport.
       # 
       # _@param_ `scrollbar` — scrollbar instance, or nil if not shown.
       # 
-      # _@return_ — paintable line exactly `rect.width` columns wide;
+      # _@return_ — paintable row exactly `rect.width` columns wide;
       # highlighted if cursor is here.
-      def paintable_line: (Integer index, Integer row_in_viewport, VerticalScrollBar? scrollbar) -> StyledString
+      def paintable_row: (Integer index, Integer row_in_viewport, VerticalScrollBar? scrollbar) -> StyledString
 
       # _@return_ — callback fired when an item is chosen — by pressing
-      # Enter on the cursor's item, or by left-clicking an item. Called as
-      # `proc.call(index, line)` with the chosen 0-based index and its
-      # {StyledString} line. Never fires when the cursor's position is
-      # outside the content (e.g. {Cursor::None}, or empty content).
+      # Enter on the cursor's item, or by left-clicking it. Called as
+      # `proc.call(index, item)` with the chosen 0-based index and the item
+      # itself. Never fires when the cursor's position is outside the content
+      # (e.g. {Cursor::None}, or empty content).
       attr_accessor on_item_chosen: Proc?
 
-      # _@return_ — callback fired when the `(index, line)` tuple under
-      # the cursor changes. Called as `proc.call(index, line)` where `line`
-      # is the {StyledString} at the cursor, or `nil` when the cursor is
+      # _@return_ — callback fired when the `(index, item)` tuple under
+      # the cursor changes (items compared with `==`). Called as
+      # `proc.call(index, item)`, with `item` `nil` when the cursor is
       # off-content ({Cursor::None}, empty list, or `index` past the last
-      # line). Fires on cursor moves (key, mouse, search), on {#cursor=},
-      # and on {#lines=}/{#add_lines} when the line at the cursor's index
+      # item). Fires on cursor moves (key, mouse, search), on {#cursor=},
+      # and on {#items=} when the item at the cursor's index
       # changes (or its in-range/out-of-range status flips). Useful for
       # keeping a details pane in sync with the highlighted row.
       attr_accessor on_cursor_changed: Proc?
 
-      # _@return_ — if true and a line is added or new content is set,
-      # auto-scrolls to the bottom — but only while the viewport is already
-      # pinned to the last line (see {#following?}). Scroll up to read older
-      # content and appends stop yanking you back down; scroll back to the
-      # bottom and tailing resumes.
+      # _@return_ — if true and new content is set, auto-scrolls to the
+      # bottom — but only while the viewport is already pinned to the last
+      # row (see {#following?}). Scroll up to read older content and
+      # incoming rows stop yanking you back down; scroll back to the bottom
+      # and tailing resumes.
       attr_accessor auto_scroll: bool
 
-      # _@return_ — top line of the viewport. 0 or positive.
-      attr_accessor top_line: Integer
+      # _@return_ — top row of the viewport. 0 or positive.
+      attr_accessor scroll_top_row: Integer
 
       # _@return_ — the list's cursor.
       attr_accessor cursor: Cursor
@@ -1865,34 +2025,42 @@ module Tuile
       # Defaults to false.
       attr_accessor show_cursor_when_inactive: bool
 
+      # _@return_ — the items, one row each.
+      attr_accessor items: ::Array[untyped]
+
+      # _@return_ — item -> row: a {StyledString}, a `String` (parsed,
+      # so embedded ANSI is honored), or anything with `#to_s`. Only the first
+      # line of a multi-line rendering is kept — one item is one row.
+      attr_accessor renderer: (Proc | Method)
+
       # Tracks cursor position within the list.
       class Cursor
         # _@param_ `position` — the initial cursor position.
         def initialize: (?position: Integer) -> void
 
-        # _@param_ `line_count` — number of lines in the list.
+        # _@param_ `item_count` — number of items in the list.
         # 
         # _@return_ — positions the cursor can land on, in
         # ascending order.
-        def candidate_positions: (Integer line_count) -> ::Array[Integer]
+        def candidate_positions: (Integer item_count) -> ::Array[Integer]
 
         # _@param_ `key` — pressed keyboard key.
         # 
-        # _@param_ `line_count` — number of lines in the list.
+        # _@param_ `item_count` — number of items in the list.
         # 
-        # _@param_ `viewport_lines` — number of visible lines.
+        # _@param_ `viewport_rows` — number of visible rows.
         # 
         # _@return_ — true if the cursor moved.
-        def handle_key: (String key, Integer line_count, Integer viewport_lines) -> bool
+        def handle_key: (String key, Integer item_count, Integer viewport_rows) -> bool
 
-        # _@param_ `line` — cursor is hovering over this line.
+        # _@param_ `item_index` — the item the cursor is hovering over.
         # 
         # _@param_ `event` — the event.
         # 
-        # _@param_ `line_count` — number of lines in the list.
+        # _@param_ `item_count` — number of items in the list.
         # 
         # _@return_ — true if the event was handled.
-        def handle_mouse: (Integer line, MouseEvent event, Integer line_count) -> bool
+        def handle_mouse: (Integer item_index, MouseEvent event, Integer item_count) -> bool
 
         # Moves the cursor to the new position. Public only because of testing.
         # 
@@ -1902,25 +2070,25 @@ module Tuile
         def go: (Integer new_position) -> bool
 
         # Moves the cursor to the last reachable position. For base {Cursor},
-        # the last line; {Limited} clamps to the last allowed position; {None}
+        # the last item; {Limited} clamps to the last allowed position; {None}
         # is a no-op.
         # 
-        # _@param_ `line_count` — number of lines in the list.
+        # _@param_ `item_count` — number of items in the list.
         # 
         # _@return_ — true if the position changed.
-        def go_to_last: (Integer line_count) -> bool
+        def go_to_last: (Integer item_count) -> bool
 
-        # _@param_ `lines`
+        # _@param_ `count`
         # 
-        # _@param_ `line_count`
-        def go_down_by: (Integer lines, Integer line_count) -> bool
+        # _@param_ `item_count`
+        def go_down_by: (Integer count, Integer item_count) -> bool
 
-        # _@param_ `lines`
-        def go_up_by: (Integer lines) -> bool
+        # _@param_ `count`
+        def go_up_by: (Integer count) -> bool
 
         def go_to_first: () -> bool
 
-        # _@return_ — 0-based line index of the current cursor position.
+        # _@return_ — 0-based item index of the current cursor position.
         attr_reader position: Integer
 
         # No cursor — cursor is disabled.
@@ -1929,20 +2097,20 @@ module Tuile
 
           # _@param_ `_key`
           # 
-          # _@param_ `_line_count`
+          # _@param_ `_item_count`
           # 
-          # _@param_ `_viewport_lines`
-          def handle_key: (String _key, Integer _line_count, Integer _viewport_lines) -> bool
+          # _@param_ `_viewport_rows`
+          def handle_key: (String _key, Integer _item_count, Integer _viewport_rows) -> bool
 
-          # _@param_ `_line`
+          # _@param_ `_item_index`
           # 
           # _@param_ `_event`
           # 
-          # _@param_ `_line_count`
-          def handle_mouse: (Integer _line, MouseEvent _event, Integer _line_count) -> bool
+          # _@param_ `_item_count`
+          def handle_mouse: (Integer _item_index, MouseEvent _event, Integer _item_count) -> bool
 
-          # _@param_ `_line_count`
-          def candidate_positions: (Integer _line_count) -> ::Array[Integer]
+          # _@param_ `_item_count`
+          def candidate_positions: (Integer _item_count) -> ::Array[Integer]
 
           # Overridden so all movement funnels — base {Cursor#go_to_last},
           # {Cursor#go_to_first}, etc., which all call {#go} — become safe
@@ -1955,39 +2123,352 @@ module Tuile
           def go: (Integer _new_position) -> bool
         end
 
-        # Cursor which can only land on specific allowed lines.
+        # Cursor which can only land on specific allowed items.
         class Limited < Cursor
           # _@param_ `positions` — allowed positions. Must not be empty.
           # 
           # _@param_ `position` — initial position.
           def initialize: (::Array[Integer] positions, ?position: Integer) -> void
 
-          # _@param_ `line`
+          # _@param_ `item_index`
           # 
           # _@param_ `event`
           # 
-          # _@param_ `_line_count`
-          def handle_mouse: (Integer line, MouseEvent event, Integer _line_count) -> bool
+          # _@param_ `_item_count`
+          def handle_mouse: (Integer item_index, MouseEvent event, Integer _item_count) -> bool
 
-          # _@param_ `line_count`
-          def candidate_positions: (Integer line_count) -> ::Array[Integer]
+          # _@param_ `item_count`
+          def candidate_positions: (Integer item_count) -> ::Array[Integer]
 
-          # _@param_ `_line_count`
-          def go_to_last: (Integer _line_count) -> bool
+          # _@param_ `_item_count`
+          def go_to_last: (Integer _item_count) -> bool
 
-          # _@param_ `lines`
+          # _@param_ `count`
           # 
-          # _@param_ `line_count`
-          def go_down_by: (Integer lines, Integer line_count) -> bool
+          # _@param_ `item_count`
+          def go_down_by: (Integer count, Integer item_count) -> bool
 
-          # _@param_ `lines`
-          def go_up_by: (Integer lines) -> bool
+          # _@param_ `count`
+          def go_up_by: (Integer count) -> bool
 
           def go_to_first: () -> bool
         end
       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
@@ -2002,19 +2483,19 @@ module Tuile
       # Skips the {Component#repaint} default's auto-clear: every row is
       # painted explicitly (with pre-padded blanks past the last line), so
       # the "fully draw over your rect" contract is met without an upfront
-      # wipe. Rows go through {Component#draw_line}, so the padding and blank
+      # wipe. Rows go through {Component#draw_text}, so the padding and blank
       # rows inherit {Component#effective_bg_color} when {#bg} is unset.
       def repaint: () -> void
 
       def on_width_changed: () -> void
 
-      # Recomputes {@clipped_lines} for the current text and rect width.
+      # Recomputes {@rows} for the current text and rect width.
       # Each line is ellipsized to fit and padded with trailing spaces out to
-      # the full width, so {#repaint} is just a lookup + {Buffer#set_line} per
-      # row. {@blank_line} covers rows past the last text line. When {#bg} is
+      # the full width, so {#repaint} is just a lookup + {Buffer#set_text} per
+      # row. {@blank_row} covers rows past the last text line. When {#bg} is
       # set, every produced line (and the blank row) has the bg applied
       # uniformly.
-      def update_clipped_lines: () -> void
+      def update_rows: () -> void
 
       # _@param_ `line`
       def apply_bg: (StyledString line) -> StyledString
@@ -2074,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
 
@@ -2082,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
@@ -2102,18 +2617,13 @@ module Tuile
 
       # Mounts this popup on the {Screen}, re-resolving its {#size} against the
       # current screen first.
-      def open: () -> void
-
-      # Constructs and opens a popup in one call.
       # 
-      # _@param_ `content`
-      # 
-      # _@param_ `modal` — see {#initialize}.
+      #   popup = Component::Popup.new(content: window).open   # construct and mount
       # 
-      # _@param_ `size` — see {#initialize}.
-      # 
-      # _@return_ — the opened popup.
-      def self.open: (?content: Component?, ?modal: bool, ?size: (Size | Fraction)) -> Popup
+      # There is deliberately no class-level `Popup.open` factory — see
+      # `DECISIONS.md` `D-popup-open`; returning `self` is what keeps the
+      # one-liner above available without one.
+      def open: () -> self
 
       # Removes this popup from the {Screen}. No-op if not currently open.
       def close: () -> void
@@ -2137,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.
@@ -2149,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`
@@ -2161,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;
@@ -2721,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`
@@ -2766,10 +3306,10 @@ module Tuile
 
       def close_menu: () -> void
 
-      # Adopts the item on row `index` as {#value} and closes the dropdown.
+      # Adopts the chosen item as {#value} and closes the dropdown.
       # 
-      # _@param_ `index`
-      def commit: (Integer index) -> void
+      # _@param_ `item`
+      def commit: (Object item) -> void
 
       def anchor: () -> void
 
@@ -2867,15 +3407,15 @@ module Tuile
       # _@param_ `content`
       def layout: (Component content) -> void
 
-      # Paints the window border via {Component#draw_line}/{Component#draw_char},
+      # Paints the window border via {Component#draw_text}/{Component#draw_char},
       # so the border cells inherit {Component#effective_bg_color} — a
       # {Component#bg_color} on the window tints border and content alike. Both
-      # border lines are clipped by *display* width, so no caption overflows the
+      # border rows are clipped by *display* width, so no caption overflows the
       # box; when the window is active the whole border — the caption's own
       # colors included — is drawn in {Theme#active_border_color}.
       def repaint_border: () -> void
 
-      # Builds the top border line: corners, {#caption} embedded at its own
+      # Builds the top border row: corners, {#caption} embedded at its own
       # width, dashes filling the remainder. The caption keeps its own styling
       # unless `fg` is set — an active window's border claims it.
       # 
@@ -2884,7 +3424,7 @@ module Tuile
       # _@param_ `fg` — the active-border color, or nil when inactive.
       def top_border: (Integer inner_w, Color? fg) -> StyledString
 
-      # Builds the bottom border line. The corners take the border color; the
+      # Builds the bottom border row. The corners take the border color; the
       # interior is plain dashes when a {#footer} component occupies the row
       # (it overpaints them) or when there's no chrome, otherwise it carries
       # {#footer_text} embedded at its own width — keeping the text's own
@@ -3053,86 +3593,573 @@ module Tuile
       def focusable?: () -> bool
     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
-    # string, so a combo over domain objects hands back the object:
-    # 
-    #   combo = Component::ComboBox.new
-    #   combo.items = User.all                       # Array of any type
-    #   combo.item_label = ->(u) { u.full_name }     # item -> shown text; default :to_s
-    #   combo.on_value_change = ->(u) { open(u) }    # fires on commit, with the item
-    #   combo.value = some_user                       # selects it; field shows its label
-    # 
-    # It's the assembly you'd otherwise wire by hand — a {TextField} plus a
-    # non-modal {Popup} over a {List} — promoted to one component. Give it a
-    # single-row {#rect}; it paints the field across that row with a `▾` in the
-    # last column and floats the dropdown above or below.
-    # 
-    # == The two values
-    # {#value} (the committed selection) and the field's typed text (a transient
-    # *query*) are deliberately distinct. Keystrokes move the query and refilter
-    # the list; only Enter/click commits, and only a commit changes {#value} and
-    # fires {#on_value_change}. An uncommitted query reverts to the current
-    # value's label when the dropdown is dismissed (ESC) or the combo loses
-    # focus. Selecting by list index (not by matching the label back) is what
-    # lets two items share a label and still resolve to the right object.
+    # 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.
     # 
-    # The dropdown is a {ListDropdown}, tinted to read as a floating panel; see
-    # it for the theming knob.
+    # == 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 ComboBox < Component
-      include Tuile::Component::HasContent
-      include Tuile::Component::HasValue
+    class MenuBar < Component
+      def initialize: () -> void
 
-      # _@param_ `items` — the candidate items (any type); also settable via {#items=}.
-      def initialize: (?items: ::Array[untyped]) -> void
+      # _@return_ — `true` — the strip takes focus, so its keys work.
+      def focusable?: () -> bool
 
-      # Selects `new_value` programmatically: updates the field to its label
-      # *without* opening the dropdown, then fires {#on_value_change}. `nil`
-      # clears the selection (blank field). The value need not be in {#items}.
-      # 
-      # _@param_ `new_value`
-      def value=: (Object new_value) -> void
+      # _@return_ — `true` — one stop for the whole strip, as on {Tabs}.
+      def tab_stop?: () -> bool
 
-      # _@return_ — the field's caret position (the combo delegates the
-      # hardware cursor to its field).
-      def cursor_position: () -> Point?
+      # _@return_ — the top-level items, in strip order. Read-only by
+      # convention; grow it through {#add_item}.
+      def items: () -> ::Array[Item]
 
-      def keyboard_hint: () -> String
+      # 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
 
-      # Re-anchors the (open) dropdown after {HasContent#rect=} has resized the
-      # field via {#layout}.
+      # 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 dropdown and reverts an uncommitted query when the combo
-      # leaves the focus chain — so tabbing away doesn't strand an open menu or
-      # a half-typed filter. Safe against re-entrancy: focus never sits inside
-      # the (non-focusable) {ListDropdown}, so closing the overlay repairs no
-      # focus.
+      # 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
 
-      # Field spans the row bar the last column, which the `▾` occupies
-      # ({HasContent} layout hook). One row, or none at all when the combo itself
-      # was given none — a starved parent must not hand out a rect it doesn't own.
+      # 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_ `field`
-      def layout: (Component field) -> void
+      # _@param_ `index`
+      def highlight=: (Integer index) -> void
 
-      # The field's key interceptor: while the dropdown is open forwards movement
-      # to it ({ListDropdown#move}), commits on Enter ({ListDropdown#choose}),
-      # and dismisses on ESC (reverting the query); opens it on Down or Enter
-      # when closed. Everything else (printable keys, editing) falls through to
+      # 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
+    # string, so a combo over domain objects hands back the object:
+    # 
+    #   combo = Component::ComboBox.new
+    #   combo.items = User.all                       # Array of any type
+    #   combo.item_label = ->(u) { u.full_name }     # item -> shown text; default :to_s
+    #   combo.on_value_change = ->(u) { open(u) }    # fires on commit, with the item
+    #   combo.value = some_user                       # selects it; field shows its label
+    # 
+    # It's the assembly you'd otherwise wire by hand — a {TextField} plus a
+    # non-modal {Popup} over a {List} — promoted to one component. Give it a
+    # single-row {#rect}; it paints the field across that row with a `▾` in the
+    # last column and floats the dropdown above or below.
+    # 
+    # == The two values
+    # {#value} (the committed selection) and the field's typed text (a transient
+    # *query*) are deliberately distinct. Keystrokes move the query and refilter
+    # the list; only Enter/click commits, and only a commit changes {#value} and
+    # fires {#on_value_change}. An uncommitted query reverts to the current
+    # value's label when the dropdown is dismissed (ESC) or the combo loses
+    # focus. Selecting by list index (not by matching the label back) is what
+    # lets two items share a label and still resolve to the right object.
+    # 
+    # The dropdown is a {ListDropdown}, tinted to read as a floating panel; see
+    # it for the theming knob.
+    # 
+    # UI-thread-confined, like every component (see {Screen}).
+    class ComboBox < Component
+      include Tuile::Component::HasContent
+      include Tuile::Component::HasValue
+
+      # _@param_ `items` — the candidate items (any type); also settable via {#items=}.
+      def initialize: (?items: ::Array[untyped]) -> void
+
+      # Selects `new_value` programmatically: updates the field to its label
+      # *without* opening the dropdown, then fires {#on_value_change}. `nil`
+      # clears the selection (blank field). The value need not be in {#items}.
+      # 
+      # _@param_ `new_value`
+      def value=: (Object new_value) -> void
+
+      # _@return_ — the field's caret position (the combo delegates the
+      # hardware cursor to its field).
+      def cursor_position: () -> Point?
+
+      # Re-anchors the (open) dropdown after {HasContent#rect=} has resized the
+      # field via {#layout}.
+      # 
+      # _@param_ `new_rect`
+      def rect=: (Rect new_rect) -> void
+
+      # Closes the dropdown and reverts an uncommitted query when the combo
+      # leaves the focus chain — so tabbing away doesn't strand an open menu or
+      # a half-typed filter. Safe against re-entrancy: focus never sits inside
+      # the (non-focusable) {ListDropdown}, so closing the overlay repairs no
+      # focus.
+      # 
+      # _@param_ `flag`
+      def active=: (bool flag) -> void
+
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
+
+      def repaint: () -> void
+
+      # Field spans the row bar the last column, which the `▾` occupies
+      # ({HasContent} layout hook). One row, or none at all when the combo itself
+      # was given none — a starved parent must not hand out a rect it doesn't own.
+      # 
+      # _@param_ `field`
+      def layout: (Component field) -> void
+
+      # The field's key interceptor: while the dropdown is open forwards movement
+      # to it ({ListDropdown#move}), commits on Enter ({ListDropdown#choose}),
+      # and dismisses on ESC (reverting the query); opens it on Down or Enter
+      # when closed. Everything else (printable keys, editing) falls through to
       # the field, whose {TextField#on_change} refilters.
       # 
       # _@param_ `key`
@@ -3152,11 +4179,11 @@ module Tuile
       # _@param_ `query`
       def matching: (String query) -> ::Array[untyped]
 
-      # Commits the item at the menu's `index`: closes the dropdown and adopts
-      # it as {#value} (which repaints the field with its label).
+      # Commits the item chosen from the menu: closes the dropdown and adopts it
+      # as {#value} (which repaints the field with its label).
       # 
-      # _@param_ `index`
-      def commit: (Integer index) -> void
+      # _@param_ `item`
+      def commit: (Object item) -> void
 
       def open_menu: () -> void
 
@@ -3166,6 +4193,9 @@ module Tuile
 
       # Sets the field's text without triggering a refilter — for programmatic
       # value changes and query reverts, which must not spring the dropdown.
+      # Every programmatic write to the field goes through here; a direct
+      # `content.text =` reaches the field's `on_change` and pops the dropdown
+      # open on a {#value=} the user never asked to browse.
       # Parks the caret at the end: `text=` only *clamps* the caret, so a
       # shorter query replaced by a longer label would otherwise strand it
       # mid-word (commit "Go", then pick "Kotlin" → caret after "Ko").
@@ -3265,11 +4295,169 @@ 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
     # content. Text is wrapped to {Rect#width} columns and any text that
-    # doesn't fit vertically is reached by scrolling: {#top_display_row}
+    # doesn't fit vertically is reached by scrolling: {#scroll_top_row}
     # follows the caret so the line being edited stays visible. There is no
     # horizontal scrolling.
     # 
@@ -3280,28 +4468,54 @@ 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
+    # instead — shell-style history recall is the motivating case — by asking
+    # {#caret_row} and {#row_count} before delegating:
+    # 
+    #   class PromptArea < Component::TextArea
+    #     protected
+    # 
+    #     def handle_text_input_key(key)
+    #       return recall_previous if key == Keys::UP_ARROW && caret_row.zero?
+    #       return recall_next if key == Keys::DOWN_ARROW && caret_row == row_count - 1
+    # 
+    #       super # anywhere else: the caret moves, and the edge still snaps
+    #     end
+    #   end
+    # 
+    # Both recalls return `true` to consume the key; app code that would rather
+    # not subclass claims the same keys through {AbstractStringField#on_key}.
     # 
     # == Implementation details
     # 
-    # The same two axes {TextField} names apply, and the wrap straddles both: an
-    # **index** counts characters into {#text} ({#caret}, a row's `start` and
-    # `length`), a **column** counts terminal cells ({#rect}, a row's `columns`,
-    # {#cursor_position}, a {MouseEvent}). A row therefore carries *both* counts,
-    # and the wrap fills each row to a column budget while recording a character
-    # span. Everything crossing between them goes through the inherited
-    # `columns_of` and the private `chars_for_column`.
-    # 
-    # The wrap walks **grapheme clusters**, not characters — a combining mark must
-    # add no columns and must not be split from its base across a row break. Note
-    # `"\r\n"` is a *single* cluster, so a hard break tests `end_with?("\n")`
-    # rather than equality.
+    # The wrap itself — and with it every conversion between a character
+    # **index** and a **row/column** — lives in {WrappedText}, a
+    # snapshot of `(text, rect.width)` this class caches and drops whenever
+    # either changes. What stays here is the widget: keys, mouse, painting, and
+    # the {#scroll_top_row} viewport, which {WrappedText} deliberately knows
+    # nothing about (it is a pure function of text and width; the viewport is
+    # stateful and needs {Rect#height}).
     class TextArea < Tuile::Component::AbstractStringField
       def initialize: () -> void
 
+      # The caret's row, counted from the text's first row — *not* from the top
+      # of the viewport (subtract {#scroll_top_row} for that).
+      # 
+      # _@return_ — a row index in `0...row_count`.
+      def caret_row: () -> Integer
+
+      # _@return_ — rows the wrapped text occupies at the current
+      # {Rect#width}; always `>= 1`, since empty text still wraps to one
+      # (empty) row.
+      def row_count: () -> Integer
+
       def cursor_position: () -> Point?
 
       # _@param_ `event`
@@ -3318,119 +4532,236 @@ module Tuile
 
       def on_width_changed: () -> void
 
-      # _@return_ — cached wrap of {#text} for the
-      # current {Rect#width}. Each entry is `{start:, length:}`.
-      def display_rows: () -> ::Array[::Hash[Symbol, Integer]]
+      # _@return_ — the current wrap of {#text} at {Rect#width}.
+      def wrap: () -> WrappedText
 
-      # _@return_ — one entry per grapheme cluster of
-      # {#text}: `{offset: <text-index>, text: <cluster>, width: <columns>}`.
-      # Rebuilt per wrap and discarded — the wrap is what's cached.
-      def cluster_table: () -> ::Array[::Hash[Symbol, Object]]
+      # _@param_ `delta` — `+1` for down, `-1` for up.
+      def move_caret_vertical: (Integer delta) -> void
 
-      # _@param_ `cluster`
-      # 
-      # _@return_ — true for a space or tab (each exactly one column).
-      def blank?: (::Hash[Symbol, Object] cluster) -> bool
+      def move_caret_to_row_start: () -> void
 
-      # _@param_ `cluster`
+      def move_caret_to_row_end: () -> void
+
+      # _@param_ `char`
       # 
-      # _@return_ — true for a hard line break. Tests the suffix rather
-      # than equality because `"\r\n"` is one grapheme cluster.
-      def newline?: (::Hash[Symbol, Object] cluster) -> bool
+      # _@return_ — always true.
+      def insert_char: (String char) -> bool
 
-      # Greedy word-wrap, filling each row to a **column** budget while recording
-      # the **character** span that produced it. Whitespace at a soft-wrap break
-      # point is absorbed (not rendered on either row). A token wider than
-      # {Rect#width} hard-wraps inside the token. Newlines force a hard break and
-      # the wrap restarts on the next cluster.
-      def compute_display_rows: () -> ::Array[::Hash[Symbol, Integer]]
+      # Keeps the caret visible by scrolling vertically.
+      def adjust_scroll_top_row: () -> void
 
-      # _@param_ `clusters`
-      # 
-      # _@param_ `index` — cluster index of the word's first glyph.
-      # 
-      # _@return_ — `[chars, columns, next_index]`
-      # for the run of non-whitespace starting at `index`.
-      def measure_word: (::Array[::Hash[Symbol, Object]] clusters, Integer index) -> [Integer, Integer, Integer]
+      # _@return_ — index of the topmost row currently visible.
+      attr_reader scroll_top_row: Integer
 
-      # Splits a token too wide for a whole row, taking entire glyphs while they
-      # fit. Consumes at least one glyph even when that single glyph is wider than
-      # the row — otherwise the wrap would not terminate (the row would stay empty
-      # and the same token be reconsidered forever). Such a row reports more
-      # columns than the rect holds and {#padded_row} drops the glyph; a
-      # 2-column glyph in a 1-column area is unpaintable either way.
+      # The word-wrapped layout of a {TextArea}'s text: which row each
+      # character lands on, and which glyphs each row paints.
       # 
-      # _@param_ `clusters`
+      #   wrap = WrappedText.new("hello world", 6)
+      #   wrap.row_count        # => 2
+      #   wrap.position_at(8)   # => [1, 2]    index 8 ("r") sits at row 1, column 2
+      #   wrap.index_at(1, 2)   # => 8         and back again
+      #   wrap.row_text(0)      # => "hello "  padded out to the width
       # 
-      # _@param_ `index`
+      # A snapshot of `(text, width)` — rebuild it whenever either changes.
       # 
-      # _@param_ `width` — column budget.
+      # == Implementation details
       # 
-      # _@return_ — `[chars, columns, next_index]`
-      def hard_wrap: (::Array[::Hash[Symbol, Object]] clusters, Integer index, Integer width) -> [Integer, Integer, Integer]
+      # Two axes meet here, and every method name says which one it speaks: an
+      # **index** counts characters into {#text}, a **column** counts terminal
+      # cells. They agree only for one-column glyphs. A {Row} therefore carries
+      # *both* counts — the wrap fills each row to a column budget while
+      # recording the character span that produced it.
+      # 
+      # The wrap walks **grapheme clusters**, not characters: a combining mark
+      # must add no columns and must not be split from its base across a row
+      # break. Note `"\r\n"` is a *single* cluster, so a hard break tests
+      # `end_with?("\n")` rather than equality. Every branch of the wrap
+      # consumes at least one cluster — `"\v"` and `"\f"` match `/\s/` but are
+      # neither blank nor a newline here, and a loop that measured them as zero
+      # and did not advance would hang the UI thread on
+      # `area.text = File.read(...)`.
+      class WrappedText
+        # _@param_ `text` — the full buffer, unwrapped.
+        # 
+        # _@param_ `width` — column budget per row; `0` or less yields a single empty row.
+        def initialize: (String text, Integer width) -> void
 
-      # Trims trailing space/tab characters off a row's visible length so the
-      # whitespace at a soft-wrap point is absorbed (not rendered) rather than
-      # left at the end of the row. Without this, soft-wrapping `"foo bar"`
-      # to width 4 would yield row 0 length 4 (`"foo "`) and the natural
-      # end-of-row caret position would coincide with row 1's start.
-      # 
-      # Both counts drop by one per trimmed character: a space and a tab each
-      # measure exactly one column.
-      # 
-      # _@param_ `row_start`
-      # 
-      # _@param_ `row_chars`
-      # 
-      # _@param_ `row_cols`
-      # 
-      # _@return_ — `[row_chars, row_cols]`
-      def trim_trailing_whitespace: (Integer row_start, Integer row_chars, Integer row_cols) -> [Integer, Integer]
+        # _@return_ — rows the text occupies; always `>= 1`, since
+        # empty text still wraps to one (empty) row.
+        def row_count: () -> Integer
 
-      # _@param_ `caret`
-      # 
-      # _@return_ — `[row_index, column]` for `caret`.
-      def caret_to_display: (Integer caret) -> [Integer, Integer]
+        # Display row holding `index`. An index inside a whitespace run absorbed
+        # by a soft wrap belongs to the row *before* the break.
+        # 
+        # _@param_ `index` — a character index into {#text}.
+        # 
+        # _@return_ — a row index in `0...row_count`.
+        def row_at: (Integer index) -> Integer
 
-      # _@param_ `row`
-      # 
-      # _@param_ `caret`
-      # 
-      # _@return_ — `caret`'s column offset within `row`.
-      def caret_column_in: (::Hash[Symbol, Integer] row, Integer caret) -> Integer
+        # _@param_ `index` — a character index into {#text}.
+        # 
+        # _@return_ — `[row, column]` for `index`.
+        def position_at: (Integer index) -> [Integer, Integer]
 
-      # _@param_ `row`
-      # 
-      # _@param_ `column` — a column offset within `row`.
-      # 
-      # _@return_ — characters from the row's start. A column landing in a
-      # wide glyph's right half resolves past it, as a click does in
-      # {TextField}.
-      def chars_for_column: (::Hash[Symbol, Integer] row, Integer column) -> Integer
+        # Inverse of {#position_at}. A column landing in a wide glyph's right
+        # half resolves *past* it, as a click does in {TextField}.
+        # 
+        # _@param_ `row` — a row index in `0...row_count`.
+        # 
+        # _@param_ `column` — a column offset within that row.
+        # 
+        # _@return_ — a character index into {#text}.
+        def index_at: (Integer row, Integer column) -> Integer
 
-      # _@param_ `row`
-      # 
-      # _@return_ — the row's text padded to `rect.width` columns. A glyph
-      # with no room left is dropped rather than half-painted.
-      def padded_row: (::Hash[Symbol, Integer] row) -> String
+        # _@param_ `row` — a row index in `0...row_count`.
+        # 
+        # _@return_ — character index where the row begins.
+        def row_start: (Integer row) -> Integer
 
-      # _@param_ `delta` — `+1` for down, `-1` for up.
-      def move_caret_vertical: (Integer delta) -> void
+        # _@param_ `row` — a row index in `0...row_count`.
+        # 
+        # _@return_ — character index one past the row's last *visible*
+        # character — whitespace absorbed by a soft wrap is excluded.
+        def row_end: (Integer row) -> Integer
+
+        # The row's glyphs, padded with spaces out to {#width}. A trailing glyph
+        # with no room left is dropped rather than half-painted. A row past the
+        # end of the text is all spaces, so a caller can paint a viewport taller
+        # than the text without a bounds check.
+        # 
+        # _@param_ `row`
+        def row_text: (Integer row) -> String
 
-      def move_caret_to_row_start: () -> void
+        # A plain Hash rather than a {Row}-style Data: this table is one entry
+        # per grapheme cluster, built and discarded inside a single {#compute_rows}
+        # call and never handed to another method as a documented type.
+        # 
+        # _@return_ — one entry per grapheme cluster of
+        # {#text}: `{offset: <text-index>, text: <cluster>, width: <columns>}`.
+        def cluster_table: () -> ::Array[::Hash[Symbol, Object]]
 
-      def move_caret_to_row_end: () -> void
+        # _@param_ `cluster`
+        # 
+        # _@return_ — true for a space or tab (each exactly one column).
+        def blank?: (::Hash[Symbol, Object] cluster) -> bool
 
-      # _@param_ `char`
-      # 
-      # _@return_ — always true.
-      def insert_char: (String char) -> bool
+        # _@param_ `cluster`
+        # 
+        # _@return_ — true for a hard line break. Tests the suffix rather
+        # than equality because `"\r\n"` is one grapheme cluster.
+        def newline?: (::Hash[Symbol, Object] cluster) -> bool
+
+        # Greedy word-wrap, filling each row to a **column** budget while recording
+        # the **character** span that produced it. Whitespace at a soft-wrap break
+        # point is absorbed (not rendered on either row). A token wider than
+        # {#width} hard-wraps inside the token. Newlines force a hard break and
+        # the wrap restarts on the next cluster.
+        # 
+        # _@return_ — one entry per row.
+        def compute_rows: () -> ::Array[Row]
 
-      # Keeps the caret visible by scrolling vertically.
-      def adjust_top_display_row: () -> void
+        # _@param_ `clusters`
+        # 
+        # _@param_ `index` — cluster index of the word's first glyph.
+        # 
+        # _@return_ — `[chars, columns, next_index]`
+        # for the run of non-whitespace starting at `index`.
+        def measure_word: (::Array[::Hash[Symbol, Object]] clusters, Integer index) -> [Integer, Integer, Integer]
+
+        # Splits a token too wide for a whole row, taking entire glyphs while they
+        # fit. Consumes at least one glyph even when that single glyph is wider than
+        # the row — otherwise the wrap would not terminate (the row would stay empty
+        # and the same token be reconsidered forever). Such a row reports more
+        # columns than {#width} holds and {#row_text} drops the glyph; a 2-column
+        # glyph in a 1-column area is unpaintable either way.
+        # 
+        # _@param_ `clusters`
+        # 
+        # _@param_ `index`
+        # 
+        # _@return_ — `[chars, columns, next_index]`
+        def hard_wrap: (::Array[::Hash[Symbol, Object]] clusters, Integer index) -> [Integer, Integer, Integer]
+
+        # Trims trailing space/tab characters off a row's visible length so the
+        # whitespace at a soft-wrap point is absorbed (not rendered) rather than
+        # left at the end of the row. Without this, soft-wrapping `"foo bar"`
+        # to width 4 would yield row 0 length 4 (`"foo "`) and the natural
+        # end-of-row caret position would coincide with row 1's start.
+        # 
+        # Both counts drop by one per trimmed character: a space and a tab each
+        # measure exactly one column.
+        # 
+        # _@param_ `row_start`
+        # 
+        # _@param_ `row_chars`
+        # 
+        # _@param_ `row_cols`
+        # 
+        # _@return_ — `[row_chars, row_cols]`
+        def trim_trailing_whitespace: (Integer row_start, Integer row_chars, Integer row_cols) -> [Integer, Integer]
+
+        # _@param_ `row`
+        # 
+        # _@param_ `index`
+        # 
+        # _@return_ — `index`'s column offset within `row`.
+        def column_in: (Row row, Integer index) -> Integer
+
+        # _@param_ `row`
+        # 
+        # _@param_ `column`
+        # 
+        # _@return_ — characters from the row's start.
+        def chars_for_column: (Row row, Integer column) -> Integer
+
+        # _@param_ `row`
+        # 
+        # _@return_ — the row's visible characters.
+        def glyphs_of: (Row row) -> String
+
+        # Mirrors {AbstractStringField}'s measurement primitive, which this class
+        # can't inherit. Per-cluster rather than whole-string so a multi-codepoint
+        # emoji measures as the one glyph a terminal draws.
+        # 
+        # _@param_ `str`
+        # 
+        # _@return_ — columns.
+        def columns_of: (String str) -> Integer
 
-      # _@return_ — index of the topmost display row currently visible.
-      attr_reader top_display_row: Integer
+        attr_reader text: String
+
+        attr_reader width: Integer
+
+        # One row's span, measured on both axes.
+        # 
+        # Both counts cover only the row's *visible* content: whitespace absorbed
+        # at a soft wrap, and the newline ending a hard one, belong to no row. So
+        # the next row's `start` may sit past this row's `start + length`, and an
+        # index in that gap resolves to the earlier row (see {WrappedText#row_at}).
+        # 
+        # @!attribute [r] start
+        #   @return [Integer] character index into {WrappedText#text} where the
+        #     row begins.
+        # @!attribute [r] length
+        #   @return [Integer] visible characters from `start`.
+        # @!attribute [r] columns
+        #   @return [Integer] terminal cells those characters occupy. Exceeds
+        #     {WrappedText#width} only for a single glyph too wide for a row.
+        class Row
+          EMPTY: Row
+
+          # _@return_ — character index into {WrappedText#text} where the
+          # row begins.
+          attr_reader start: Integer
+
+          # _@return_ — visible characters from `start`.
+          attr_reader length: Integer
+
+          # _@return_ — terminal cells those characters occupy. Exceeds
+          # {WrappedText#width} only for a single glyph too wide for a row.
+          attr_reader columns: Integer
+        end
+      end
     end
 
     # A read-only viewer for prose: chunks of formatted text that scroll
@@ -3524,7 +4855,7 @@ module Tuile
       # Drops the last `n` hard lines from the buffer — the inverse of building
       # up a tail with {#append} / {#add_line}, so a caller can `remove` then
       # `append` to rewrite a damaged tail in place. Operates on **hard lines**
-      # (the `\n`-delimited entries), not wrapped physical rows. `n == 0` and the
+      # (the `\n`-delimited entries), not wrapped rows. `n == 0` and the
       # empty buffer are no-ops; `n >= hard-line count` empties the buffer.
       # 
       # _@param_ `n` — number of hard lines to drop; must be >= 0.
@@ -3541,7 +4872,7 @@ module Tuile
       # - an empty `Range` (e.g. `2...2`, or `size...size` at the end) is
       #   *insertion* at that position — nothing removed. {#insert} aliases this.
       # 
-      # Splices in place — only the affected slice of the physical-row buffer is
+      # Splices in place — only the affected slice of the row buffer is
       # touched, no preceding lines re-wrapped (cost O(from + length + new
       # content)). A no-op when the replacement equals the covered range, so
       # `replace(n...n, "")` is cheap.
@@ -3565,10 +4896,27 @@ module Tuile
       # Clears the text. Equivalent to `text = ""`.
       def clear: () -> void
 
+      # 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: 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 —
+      # arriving there re-arms {#following?}.
+      def scroll_half_page_down: () -> void
+
       def focusable?: () -> bool
 
       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
 
@@ -3580,7 +4928,7 @@ module Tuile
       # Skips the {Component#repaint} default's auto-clear: every row is
       # painted explicitly (with padded blanks past the last line), so the
       # "fully draw over your rect" contract is met without an upfront wipe.
-      # Rows go through {Component#draw_line}, so content and blank rows inherit
+      # Rows go through {Component#draw_text}, so content and blank rows inherit
       # {Component#effective_bg_color} (a {#bg_color} set here or on an ancestor).
       def repaint: () -> void
 
@@ -3606,7 +4954,7 @@ module Tuile
       # _@param_ `what`
       def normalize_replace_range: ((::Range[untyped] | Integer) range, ?Integer size, ?String what) -> [Integer, Integer]
 
-      # Hard-line index where `region` begins in {@hard_lines} — derived
+      # Hard-line index where `region` begins in {@lines} — derived
       # by summing the line counts of all regions that precede it.
       # 
       # _@param_ `region`
@@ -3647,7 +4995,7 @@ module Tuile
       def append_to_region: (Region region, (String | StyledString)? str) -> void
 
       # Drops the last `n` hard lines from `region`'s tail via
-      # {#splice_hard_lines}. `n` is clamped to the region's current
+      # {#splice_lines}. `n` is clamped to the region's current
       # line count; callers guarantee `n > 0` and the region is
       # non-empty (the {Region#remove_last_n_lines} guard handles the
       # no-op cases).
@@ -3658,7 +5006,7 @@ module Tuile
       def remove_last_n_from_region: (Region region, Integer n) -> void
 
       # Drops `region` from {@regions}: its hard lines are removed via
-      # {#splice_hard_lines}, the handle is detached, and the always-one
+      # {#splice_lines}, the handle is detached, and the always-one
       # default is restored if the removal would have left zero regions.
       # Skips the rewrap / invalidate work when the region was empty
       # (the buffer didn't change), but always detaches.
@@ -3666,7 +5014,7 @@ module Tuile
       # _@param_ `region`
       def remove_region: (Region region) -> void
 
-      # Adjusts region line counts after a {@hard_lines} splice that removed
+      # Adjusts region line counts after a {@lines} splice that removed
       # `removed_count` lines at `from` and inserted `added_count`. Subtracts
       # each region's overlap with the removed range, then credits the added
       # lines to the first region that lost lines. Pure insertions have no such
@@ -3681,68 +5029,71 @@ module Tuile
       def update_region_counts: (Integer from, Integer removed_count, Integer added_count) -> void
 
       # _@return_ — number of visible lines.
-      def viewport_lines: () -> Integer
+      def viewport_rows: () -> Integer
 
-      # _@return_ — the max value of {#top_line} for scroll-key clamping.
-      def top_line_max: () -> Integer
+      # _@return_ — the max value of {#scroll_top_row} for scroll-key clamping.
+      def scroll_top_row_max: () -> Integer
 
-      # Full rebuild of {@physical_lines} and {@hard_line_wrap_counts}
-      # from {@hard_lines}. Called when wrap width changes (which
+      # _@return_ — half a viewport, at least one row, for the half-page
+      # scroll verbs and their keys.
+      def half_page_rows: () -> Integer
+
+      # Full rebuild of {@rows} and {@line_wrap_counts}
+      # from {@lines}. Called when wrap width changes (which
       # invalidates every cached row count) and from {#text=} (which
       # replaces the whole logical model). Mid-buffer mutators splice
-      # incrementally via {#splice_hard_lines} and do *not* go through
-      # here. Clamps {@top_line} if the new line count puts it out of
+      # incrementally via {#splice_lines} and do *not* go through
+      # here. Clamps {@scroll_top_row} if the new line count puts it out of
       # range.
       def rewrap: () -> void
 
-      # Wraps `hard_line` at `width` and returns the padded physical rows
-      # alongside the row count. Empty hard lines (e.g. from a `"\n\n"`
-      # run) and degenerate `width <= 0` both emit a single {@blank_line}
+      # Wraps `line` at `width` and returns the padded rows alongside the
+      # row count. Empty lines (e.g. from a `"\n\n"`
+      # run) and degenerate `width <= 0` both emit a single {@blank_row}
       # row, matching what `@text.wrap(width).map { |l| pad_to(l, width) }`
       # would have produced.
       # 
-      # _@param_ `hard_line`
+      # _@param_ `line`
       # 
       # _@param_ `width`
-      def wrap_hard_line: (StyledString hard_line, Integer width) -> [::Array[StyledString], Integer]
+      def wrap_line: (StyledString line, Integer width) -> [::Array[StyledString], Integer]
 
-      # Appends `hard_line` to the tail of {@hard_lines}, updating the
-      # wrap-count cache and {@physical_lines} in lockstep.
+      # Appends `line` to the tail of {@lines}, updating the
+      # wrap-count cache and {@rows} in lockstep.
       # 
-      # _@param_ `hard_line`
+      # _@param_ `line`
       # 
       # _@param_ `width`
-      def push_hard_line: (StyledString hard_line, Integer width) -> void
-
-      # Pops the last hard line, the corresponding cache entry, and the
-      # physical rows that hard line contributed. Returns the popped
-      # hard line.
-      def pop_hard_line: () -> StyledString
-
-      # Splices `new_hard_lines` into the buffer in place of the `count`
-      # hard lines starting at index `from`. Updates {@hard_lines},
-      # {@hard_line_wrap_counts}, and {@physical_lines} consistently.
-      # The starting physical-row offset is computed in O(`from`) integer
-      # adds via the cache — no wraps of preceding hard lines. Wraps are
+      def push_line: (StyledString line, Integer width) -> void
+
+      # Pops the last line, the corresponding cache entry, and the rows
+      # that line contributed. Returns the popped line.
+      def pop_line: () -> StyledString
+
+      # Splices `new_lines` into the buffer in place of the `count` lines
+      # starting at index `from`. Updates {@lines},
+      # {@line_wrap_counts}, and {@rows} consistently.
+      # The starting row offset is computed in O(`from`) integer
+      # adds via the cache — no wraps of preceding lines. Wraps are
       # done only for the new content, so total cost is
-      # `O(from + count + new_hard_lines.sum(&:display_width))`.
+      # `O(from + count + new_lines.sum(&:display_width))`.
       # 
       # _@param_ `from`
       # 
-      # _@param_ `count` — number of existing hard lines to remove.
+      # _@param_ `count` — number of existing lines to remove.
       # 
-      # _@param_ `new_hard_lines`
-      def splice_hard_lines: (Integer from, Integer count, ::Array[StyledString] new_hard_lines) -> void
+      # _@param_ `new_lines`
+      def splice_lines: (Integer from, Integer count, ::Array[StyledString] new_lines) -> void
 
       # _@param_ `idx`
       # 
-      # _@return_ — the {@physical_lines} index where the hard line
-      # at {@hard_lines}`[idx]` starts. O(`idx`) integer adds via the
+      # _@return_ — the {@rows} index where the line
+      # at {@lines}`[idx]` starts. O(`idx`) integer adds via the
       # wrap-count cache.
-      def phys_offset_at: (Integer idx) -> Integer
+      def row_offset_at: (Integer idx) -> Integer
 
-      # Rebuilds the joined {StyledString} from {@hard_lines}, inserting a
-      # default-styled `"\n"` between hard lines. Called from the {#text}
+      # Rebuilds the joined {StyledString} from {@lines}, inserting a
+      # default-styled `"\n"` between lines. Called from the {#text}
       # reader when the cache is cold. Cost is O(total spans).
       def build_text: () -> StyledString
 
@@ -3752,19 +5103,19 @@ module Tuile
       def wrap_width: () -> Integer
 
       # _@param_ `delta` — negative scrolls up, positive scrolls down.
-      def move_top_line_by: (Integer delta) -> void
+      def move_scroll_top_row_by: (Integer delta) -> void
 
-      # _@param_ `target` — desired top line; clamped to `[0, top_line_max]`.
-      def move_top_line_to: (Integer target) -> void
+      # _@param_ `target` — desired top line; clamped to `[0, scroll_top_row_max]`.
+      def move_scroll_top_row_to: (Integer target) -> void
 
       # Gated on {#following?}: once the user scrolls up off the bottom the
       # viewport pin is skipped, so reading older content is not interrupted
-      # by incoming lines. {#top_line=} re-arms `@follow` when the viewport
+      # by incoming lines. {#scroll_top_row=} re-arms `@follow` when the viewport
       # returns to the bottom.
-      def update_top_line_if_auto_scroll: () -> void
+      def update_scroll_top_row_if_auto_scroll: () -> void
 
       # _@return_ — whether the viewport is pinned to the last line.
-      # Drives {#following?}: re-evaluated on every {#top_line=}.
+      # Drives {#following?}: re-evaluated on every {#scroll_top_row=}.
       def at_bottom?: () -> bool
 
       def scrollbar_visible?: () -> bool
@@ -3775,24 +5126,24 @@ module Tuile
       # `width <= 0` returns {StyledString::EMPTY} to handle the degenerate
       # `wrap_width == 0` case (rect.width == 1 with scrollbar).
       # 
-      # _@param_ `line`
+      # _@param_ `row`
       # 
       # _@param_ `width`
-      def pad_to: (StyledString line, Integer width) -> StyledString
+      def pad_to: (StyledString row, Integer width) -> StyledString
 
-      # _@param_ `index` — 0-based index into `@physical_lines`.
+      # _@param_ `index` — 0-based index into `@rows`.
       # 
       # _@param_ `row_in_viewport` — 0-based row within the viewport.
       # 
       # _@param_ `scrollbar`
       # 
-      # _@return_ — paintable line exactly `rect.width` columns wide.
-      # Body lines come pre-padded from {#rewrap}, so this reduces to a lookup
+      # _@return_ — paintable row exactly `rect.width` columns wide.
+      # Body rows come pre-padded from {#rewrap}, so this reduces to a lookup
       # plus a concat of the scrollbar glyph when one is present.
-      def paintable_line: (Integer index, Integer row_in_viewport, VerticalScrollBar? scrollbar) -> StyledString
+      def paintable_row: (Integer index, Integer row_in_viewport, VerticalScrollBar? scrollbar) -> StyledString
 
-      # _@return_ — index of the first visible physical line.
-      attr_accessor top_line: Integer
+      # _@return_ — index of the first visible row.
+      attr_accessor scroll_top_row: Integer
 
       # _@return_ — `:gone` or `:visible`.
       attr_accessor scrollbar_visibility: Symbol
@@ -3986,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
@@ -4021,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
@@ -4088,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`,
@@ -4114,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) —
@@ -4328,12 +5692,13 @@ module Tuile
     # initial state, and assigning it is the only way back, since Space on the
     # already-selected row is a no-op rather than a deselect.
     # 
-    # Composes rather than subclasses, like {ComboBox}: a {List} is its single
-    # {HasContent} child, which is where the cursor, scrolling, the scrollbar
-    # and per-row mouse hit-testing come from. `content` is that list, so an app
-    # can tune it (`scrollbar_visibility`, `show_cursor_when_inactive`, …). Rows
-    # beyond {#rect}'s height scroll; the inner list is the tab stop, not the
-    # group.
+    # Composes rather than subclasses, like {ComboBox}: a {List} of the items
+    # is its single {HasContent} child, which is where the cursor, scrolling,
+    # the scrollbar and per-row mouse hit-testing come from — the group only
+    # supplies the {List#renderer} that puts the marker in front of the label.
+    # `content` is that list, so an app can tune it (`scrollbar_visibility`,
+    # `show_cursor_when_inactive`, …). Rows beyond {#rect}'s height scroll; the
+    # inner list is the tab stop, not the group.
     # 
     # == The cursor is chrome
     # The cursor and the selection are two independent things, as in
@@ -4357,7 +5722,7 @@ module Tuile
     # == Implementation details
     # Two `==`-equal items share one selection, so selecting either marks both
     # rows; two *distinct* items that merely render the same label stay
-    # independent, because a row resolves to an item by index.
+    # independent, because a row resolves to its own item, never to its label.
     # 
     # Rows are `(*) `/`( ) ` literals, mirroring {Checkbox}'s convention rather
     # than importing constants from it. ASCII deliberately: `(•)` would measure
@@ -4374,6 +5739,15 @@ module Tuile
       # _@param_ `value` — the initially selected item. Seeds the backing ivar directly, so no listener fires and assignment order doesn't matter to a form helper.
       def initialize: (?items: ::Array[untyped], ?value: Object?) -> void
 
+      # _@return_ — the presented items.
+      def items: () -> ::Array[untyped]
+
+      # Replaces the presented rows, leaving {#value} untouched and clamping the
+      # cursor back into range.
+      # 
+      # _@param_ `new_items`
+      def items=: (::Array[untyped] new_items) -> void
+
       # Selects `new_value`, firing {HasValue#on_value_change} when it really
       # changed. The cursor stays where it is.
       # 
@@ -4393,19 +5767,26 @@ module Tuile
       # _@param_ `list`
       def layout: (Component list) -> void
 
-      # Selects the item on row `index`; an index outside {#items} is ignored.
+      # Selects the item on row `index`; an index outside {#items} is ignored —
+      # {List::Cursor::None}'s `-1` would otherwise select the *last* item.
       # 
       # _@param_ `index`
       def select_at: (Integer index) -> void
 
-      # Re-renders every row from the current items, labels and selection.
-      def rebuild_rows: () -> void
+      # _@param_ `item`
+      # 
+      # _@return_ — the item's row: its label behind a selection
+      # marker. The {List} calls this at paint time, so the marker tracks
+      # {#value} without re-rendering anything but the visible rows.
+      def render_row: (Object item) -> StyledString
 
       # Pulls an over-range cursor back onto the last row (row 0 when there are
-      # none). {List#lines=} leaves a stale cursor alone, which would strand it
+      # none). {List#items=} leaves a stale cursor alone, which would strand it
       # off-content: no highlight, a dead Enter, and a Space that resolves to
       # `nil` and silently clears the selection.
-      def clamp_cursor: () -> void
+      # 
+      # _@param_ `item_count` — size of the incoming item list.
+      def clamp_cursor: (Integer item_count) -> void
 
       # _@param_ `item`
       # 
@@ -4441,14 +5822,182 @@ module Tuile
 
       def on_focus: () -> void
 
-      # _@return_ — the presented items.
-      attr_accessor items: ::Array[untyped]
-
       # _@return_ — item -> row label (a `String`, {StyledString}, or
       # anything with `#to_s`); `:to_s` by default.
       attr_accessor item_label: (Proc | Method)
     end
 
+    # A transient message in the screen's top-right corner — the TTY toast:
+    # 
+    #   Component::Notification.show("Saved")
+    #   Component::Notification.show("Disk full", color: Theme.ref(:error))
+    # 
+    #   ┌─────────┐  ← flush: row 0, right edge at the last column
+    #   │Saved    │  ← oldest on top, retires in 3 s
+    #   │Disk full│  ← then this one, 3 s after that
+    #   └─────────┘
+    # 
+    # {show} is the only entry point ({new} is private): it finds the live
+    # notification and appends to it, so a burst stacks as entries in one box
+    # instead of opening five overlapping ones.
+    # 
+    # One repeating ticker retires the **oldest** entry every {DISPLAY_SECONDS}
+    # and closes the box when the last one goes — five messages raised together
+    # appear at once and drain over fifteen seconds. A message arriving mid-cycle
+    # waits its turn and does *not* restart the clock, so the bottom entry of a
+    # full box is visible for about `N × DISPLAY_SECONDS`. Past {MAX_MESSAGES} a
+    # message is dropped and reported to {Tuile.logger}; an app notifying faster
+    # than that wants a {Component::LogWindow}.
+    # 
+    # The box is flush to the corner, at most {WIDTH_FRACTION} of the screen wide
+    # (floor {MIN_CAP_WIDTH}) and {HEIGHT_FRACTION} tall, and **grows but never
+    # shrinks** while it lives; a long message wraps to {MAX_ROWS_PER_MESSAGE}
+    # rows and is then ellipsized, and entries past the height cap wait unpainted.
+    # `DECISIONS.md` `D-notification` has why each of those is what it is.
+    # 
+    # Three things it deliberately doesn't do:
+    # 
+    # - **Take focus, or receive keys.** A non-modal popup sits off the
+    #   key-dispatch scope ({ScreenPane#handle_key}), so not even {Popup}'s
+    #   `q`/ESC arrives here. A left click *on the box* dismisses
+    #   ({#handle_mouse}); an app wanting a key registers a global shortcut and
+    #   calls {#close}. A click *elsewhere* does not — this is the one popup
+    #   with {Popup#close_on_outside_click?} false, since a toast is timed and
+    #   an unrelated click is not about it.
+    # - **Follow a theme flip.** A `Theme::Ref` `color:` is resolved once, when
+    #   the message is added — a toast lives seconds, so there is no
+    #   {Component#on_theme_changed} rebuild.
+    # - **Take a size.** {#size=} raises; the messages decide.
+    class Notification < Tuile::Component::Popup
+      MAX_MESSAGES: Integer
+      MAX_ROWS_PER_MESSAGE: Integer
+      DISPLAY_SECONDS: Float
+      WIDTH_FRACTION: Float
+      HEIGHT_FRACTION: Float
+      MIN_CAP_WIDTH: Integer
+      SPACE: StyledString
+      ROW_BREAK: StyledString
+
+      # Shows `text` in the corner, creating the box if none is open and
+      # appending to it if one is.
+      # 
+      # _@param_ `text` — the message. A `String` is parsed via {StyledString.parse}, so embedded ANSI is honored. `nil` and the empty string are no-ops (nothing is shown, nothing is created).
+      # 
+      # _@param_ `color` — applied to every span of the message via {StyledString#with_fg}. A {Theme::Ref} is resolved against the current theme *now* — see the class docs on theme following. `nil` leaves the message's own colors alone.
+      # 
+      # _@return_ — the live notification, or `nil` when `text`
+      # was empty.
+      def self.show: ((String | StyledString)? text, ?color: (Color | Theme::Ref | Symbol | Integer | ::Array[Integer])?) -> Notification?
+
+      def initialize: () -> void
+
+      # Load-bearing, not cosmetic: focus landing inside a non-modal popup sits
+      # outside the key-dispatch scope, where {ScreenPane#handle_key} delivers to
+      # nobody — every keystroke would go dead until the user pressed Tab.
+      # 
+      # _@return_ — false.
+      def focusable?: () -> bool
+
+      # _@return_ — false — see {#focusable?}.
+      def tab_stop?: () -> bool
+
+      # Appends a message, dropping it (with a {Tuile.logger} warning) once
+      # {MAX_MESSAGES} are held. Public so a caller holding the instance can
+      # append without repeating {show}'s lookup.
+      # 
+      # _@param_ `text` — see {show}. Empty is a no-op.
+      # 
+      # _@param_ `color` — see {show}.
+      def add_message: ((String | StyledString)? text, ?color: (Color | Theme::Ref | Symbol | Integer | ::Array[Integer])?) -> void
+
+      # Recomputes the box from its messages and re-anchors it to the screen's
+      # top-right corner — so a SIGWINCH re-wraps and re-anchors, where
+      # {Popup#reposition} would have kept the stale left column of a *derived*
+      # position (off-screen entirely if the terminal narrowed).
+      # 
+      # Rebuilds the {TextView}'s text too, and every mutation routes through
+      # here, because the four are one computation: the wrap width *is* the box
+      # width, the height *is* the wrapped row count, the left edge *is* derived
+      # from the width.
+      def reposition: () -> void
+
+      # A notification is sized by its messages, so this always raises. Failing
+      # loudly beats accepting a size the next {#reposition} would discard.
+      # 
+      # _@param_ `_new_size`
+      def size=: ((Size | Fraction) _new_size) -> void
+
+      # A left click dismisses the whole box, every message with it. Other buttons
+      # are consumed and inert — including the scroll wheel, which would otherwise
+      # nuke the box on a stray spin.
+      # 
+      # Deliberately *replaces* rather than augments: neither `super` nor
+      # {HasContent#handle_mouse} may run, since both end at a
+      # `screen.focused = …` inside this subtree (see {#focusable?}).
+      # 
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
+
+      def on_attached: () -> void
+
+      def on_detached: () -> void
+
+      # Retires the oldest message, closing the box when it was the last. Runs on
+      # the event-loop thread, from the ticker.
+      def retire_oldest: () -> void
+
+      # Syncs the retirement clock from the invariant "something to retire, and on
+      # screen" — the sole writer of `@ticker`. Four sites change whether it is
+      # wanted (append, a retirement that empties the queue, {#close}, detach),
+      # which is the 2×2 a start-in-{#on_attached} / cancel-in-{#on_detached} pair
+      # gets half wrong. The early return is also what keeps an append from
+      # *restarting* the clock and extending the oldest message's life.
+      def sync_ticker: () -> void
+
+      # _@param_ `text`
+      # 
+      # _@param_ `color`
+      def build_message: ((String | StyledString)? text, (Color | Theme::Ref | Symbol | Integer | ::Array[Integer])? color) -> StyledString
+
+      # Columns the message would like, ignoring wrapping — the *widest* of its
+      # hard lines, not the sum of its spans (which would add every line
+      # together for a message carrying `\n`).
+      # 
+      # _@param_ `message`
+      def natural_width: (StyledString message) -> Integer
+
+      # Grow-only: the high-water mark is kept in *desired* columns and the cap
+      # is applied here, last. Storing the clamped value instead would let a
+      # SIGWINCH that narrows the terminal ratchet the box permanently down to
+      # the narrow cap, with nothing to restore it when the terminal widens.
+      def box_width: () -> Integer
+
+      def cap_width: () -> Integer
+
+      # _@return_ — at least 3: two border rows plus one row of message.
+      def cap_height: () -> Integer
+
+      # Wraps one message to `width` columns, capped at {MAX_ROWS_PER_MESSAGE}
+      # rows.
+      # 
+      # The overflow is ellipsized from the *joined remainder*, not by
+      # ellipsizing the last kept row: that row usually already fits `width`, so
+      # {StyledString#ellipsize} would be a no-op and the message would be
+      # truncated with no `…` to say so.
+      # 
+      # _@param_ `message`
+      # 
+      # _@param_ `width`
+      def wrap_message: (StyledString message, Integer width) -> ::Array[StyledString]
+
+      # Joins pre-wrapped rows into one {StyledString} with `\n` separators, so
+      # {TextView} takes them as hard lines and its own wrap is a no-op over
+      # them (each row already fits the width it will be painted at).
+      # 
+      # _@param_ `rows`
+      def join_rows: (::Array[StyledString] rows) -> StyledString
+    end
+
     # A one-row progress bar: a run of `█` growing left to right across {#rect},
     # over a `░` track.
     # 
@@ -4710,18 +6259,20 @@ module Tuile
     # highlight, and reads the pick.
     # 
     #   drop = Component::ListDropdown.new
-    #   drop.on_item_chosen = ->(index, _line) { commit(index) } # caller commits
+    #   drop.renderer = method(:label_for)                 # caller renders
+    #   drop.on_item_chosen = ->(_index, item) { commit(item) }   # caller commits
     #   # …then, from the driver's key handler:
-    #   drop.lines = matches.map { |m| render(m) }   # caller filters + renders
+    #   drop.items = matches                         # caller filters
     #   drop.anchor_to(rect, rows: matches.size)     # below the driver, or flipped
     #   drop.open
     #   return true if drop.move(key)  # Up/Down/PgUp/PgDn/^U/^D → list scroll
     #   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.
@@ -4739,21 +6290,36 @@ module Tuile
 
       def initialize: () -> void
 
-      # _@param_ `lines` — the rows to show; see {List#lines=}.
-      def lines=: (::Array[untyped] lines) -> void
+      # _@param_ `items` — the items to show, one row each; see {List#items=}.
+      def items=: (::Array[untyped] items) -> void
 
-      # _@return_ — the current rows.
-      def lines: () -> ::Array[StyledString]
+      # _@return_ — the items currently shown.
+      def items: () -> ::Array[untyped]
+
+      # _@param_ `proc` — item -> row; see {List#renderer}.
+      def renderer=: ((Proc | Method) proc) -> void
 
       # _@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
@@ -4779,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}
@@ -4802,6 +6411,8 @@ module Tuile
       # stealing focus — so a driving text input never loses its caret
       # mid-interaction.
       class Menu < Tuile::Component::List
+        DEFAULT_RENDERER: Proc
+
         def focusable?: () -> bool
 
         def tab_stop?: () -> bool
@@ -4830,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`.
       # 
@@ -4885,12 +6494,13 @@ module Tuile
     # Treat it as *unordered*: it iterates in toggle order, so use
     # `cg.items & cg.value.to_a` when you need {#items} order.
     # 
-    # Composes rather than subclasses, like {ComboBox}: a {List} is its single
-    # {HasContent} child, which is where the cursor, scrolling, the scrollbar and
-    # per-row mouse hit-testing come from. `content` is that list, so an app can
-    # tune it (`scrollbar_visibility`, `show_cursor_when_inactive`, …). Rows
-    # beyond {#rect}'s height scroll; the inner list is the tab stop, not the
-    # group.
+    # Composes rather than subclasses, like {ComboBox}: a {List} of the items is
+    # its single {HasContent} child, which is where the cursor, scrolling, the
+    # scrollbar and per-row mouse hit-testing come from — the group only supplies
+    # the {List#renderer} that puts the box in front of the label. `content` is
+    # that list, so an app can tune it (`scrollbar_visibility`,
+    # `show_cursor_when_inactive`, …). Rows beyond {#rect}'s height scroll; the
+    # inner list is the tab stop, not the group.
     # 
     # == +items+ is chrome; +value+ is authoritative
     # {#items=} changes only what is *presented*. It never touches {#value} and
@@ -4908,7 +6518,7 @@ module Tuile
     # mutated after being selected becomes unfindable. Two `==`-equal items also
     # share one selection — their rows check and uncheck together — whereas two
     # *distinct* items that merely render the same label toggle independently,
-    # because a row resolves to an item by index.
+    # because a row resolves to its own item, never to its label.
     # 
     # Rows repeat {Checkbox}'s `[x] `/`[ ] ` glyph convention rather than
     # importing a constant from it.
@@ -4924,6 +6534,14 @@ module Tuile
       # _@param_ `value` — the initial selection. Seeds the backing ivar directly, so no listener fires and assignment order doesn't matter to a form helper.
       def initialize: (?items: ::Array[untyped], ?value: ::Enumerable[untyped]?) -> void
 
+      # _@return_ — the presented items.
+      def items: () -> ::Array[untyped]
+
+      # Replaces the presented rows, leaving {#value} untouched.
+      # 
+      # _@param_ `new_items`
+      def items=: (::Array[untyped] new_items) -> void
+
       # _@return_ — the frozen empty set — {HasValue#empty?} means nothing is
       # selected.
       def empty_value: () -> ::Set[untyped]
@@ -4949,13 +6567,23 @@ module Tuile
       def layout: (Component list) -> void
 
       # Flips membership of the item on row `index`; an index outside {#items} is
-      # ignored.
+      # ignored — {List::Cursor::None}'s `-1` would otherwise toggle the *last*
+      # item.
       # 
       # _@param_ `index`
       def toggle_at: (Integer index) -> void
 
-      # Re-renders every row from the current items, labels and selection.
-      def rebuild_rows: () -> void
+      # Flips `item`'s membership of {#value}.
+      # 
+      # _@param_ `item`
+      def toggle: (Object item) -> void
+
+      # _@param_ `item`
+      # 
+      # _@return_ — the item's row: its label behind a checkmark box.
+      # The {List} calls this at paint time, so the boxes track {#value}
+      # without re-rendering anything but the visible rows.
+      def render_row: (Object item) -> StyledString
 
       # _@param_ `new_value`
       # 
@@ -4992,9 +6620,6 @@ module Tuile
 
       def on_focus: () -> void
 
-      # _@return_ — the presented items.
-      attr_accessor items: ::Array[untyped]
-
       # _@return_ — item -> row label (a `String`, {StyledString}, or
       # anything with `#to_s`); `:to_s` by default.
       attr_accessor item_label: (Proc | Method)
@@ -5226,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).
@@ -5257,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 —
@@ -5563,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.
     # 
@@ -5699,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
 
@@ -5773,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
@@ -5826,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.
@@ -5836,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.
@@ -5867,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
@@ -5874,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
 
@@ -5892,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
@@ -5905,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`.
@@ -5919,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
@@ -6047,7 +7804,7 @@ module Tuile
     # An empty {StyledString} returns a single empty entry, like `"".split`.
     def lines: () -> ::Array[StyledString]
 
-    # Word-wraps to physical lines that each fit within `width` display
+    # Word-wraps to rows that each fit within `width` display
     # columns, preserving spans and styles across breaks. Greedy word-wrap,
     # hard-break for words wider than `width`, leading whitespace dropped on
     # wrapped continuations, hard `"\n"` breaks preserved as separate output
@@ -6070,7 +7827,7 @@ module Tuile
     # 
     # _@param_ `width` — target column width. `nil` or `<= 0` skips wrapping and returns each hard-line as-is, so callers can pass a stale viewport width without crashing.
     # 
-    # _@return_ — one entry per physical (output) line.
+    # _@return_ — one entry per output row.
     # An empty receiver returns `[]`.
     def wrap: (Integer? width) -> ::Array[StyledString]
 
@@ -6103,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
@@ -6124,23 +7915,23 @@ module Tuile
     # _@param_ `len`
     def slice_spans: (Integer start, Integer len) -> StyledString
 
-    # _@param_ `hard_line` — one hard-broken line — no embedded `"\n"`.
+    # _@param_ `line` — one line — no embedded `"\n"`.
     # 
     # _@param_ `width`
-    def wrap_one: (StyledString hard_line, Integer width) -> ::Array[StyledString]
+    def wrap_one: (StyledString line, Integer width) -> ::Array[StyledString]
 
     # Splits into whitespace/word tokens by **grapheme cluster**, not character:
     # a cluster is the unit a terminal draws, so measuring its parts separately
     # would both mis-total an emoji sequence and let a wrap break a letter away
     # from its combining mark.
     # 
-    # _@param_ `hard_line`
+    # _@param_ `line`
     # 
     # _@return_ — tokens shaped `[type, glyphs, w]` where `type` is
     # `:space` or `:word`, `glyphs` is an `Array<[String, Style, Integer]>`
     # (grapheme cluster, style, display width), and `w` is the token's total
     # width.
-    def tokenize_for_wrap: (StyledString hard_line) -> ::Array[::Array[untyped]]
+    def tokenize_for_wrap: (StyledString line) -> ::Array[::Array[untyped]]
 
     # Like {#each_char_with_style} but per grapheme cluster. A cluster spanning a
     # style boundary takes the style of its first span — pathological input, and
@@ -6506,10 +8297,10 @@ module Tuile
   class VerticalScrollBar
     # _@param_ `height` — number of rows in the scrollbar (== viewport height).
     # 
-    # _@param_ `line_count` — total number of content lines.
+    # _@param_ `row_count` — total number of content rows.
     # 
-    # _@param_ `top_line` — index of the first visible content line.
-    def initialize: (Integer height, line_count: Integer, top_line: Integer) -> void
+    # _@param_ `scroll_top_row` — index of the first visible content row.
+    def initialize: (Integer height, row_count: Integer, scroll_top_row: Integer) -> void
 
     # Returns the scrollbar character for the given viewport row.
     #